documentation

War stories When talking about software documentation we usually describe the what and how, but explaining the reason (why) is it left out. Giving a background about why the team took some decisions can help developers understand better why the software is the way it is. Documentation is a foundational part of software I would say that nobody doubts that a piece os software without documentation is not useful. Software can have a big complexity and maintaining it and extend it can be hard if there is no guide. [Read More]

Misconceptions about code comments I have been working in this industry since 2008, and it seems an idea is spreading through software companies: code comments are considered harmful. Is that true? Where did all start? I think that this idea started with the Clean Code book and the subsequent talks by Robert C. Martin. Uncle Bob (as people use to call him), has the idea that code should be self-explanatory, and if there is a comment, it is because code is not well structured. [Read More]

Donald E. Knuth coined the term Literate programming in this paper he wrote almost 40 years ago. Knuth wrote a tool called WEB as a demonstration of what Literate Programming should be. This tool would understand Pascal and TeX code, using Pascal code to create a binary executable and using TeX code to compile its documentation file. Pascal code would be a bit different because of the use of predefined macros and it would be interleaved by TeX code describing what actions execute. [Read More]