documentation

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]