3 ms·

I think that clean code is more useful than documentation. However in some cases it's not clear why some code was written that way, more than how it was written

I think that clean code is more useful than documentation. However in some cases it's not clear why some code was written that way, more than how it was written. In that case a couple of lines of documentation helps IMO. Also, if you write relatively small and short functions and you document the goal, the inputs and the result, then the code is quite self explanatory.

nicklecompte 5y ago
It really depends on the domain. I think your comment is generally true for “most code,” since most code involves relatively simple concepts familiar to most programmers, and is performing a fairly clear task. But there are many functions where it is reasonable to have even hundreds of words worth of comments: - anything that heavily uses intrinsics and requires the programmer to have a detailed mental model of the CPU in order to analyze (e.g. making an ASCII table of the register state at each major step of the program). Likewise with assembly programming, though obviously that’s a special case. - a particularly sophisticated graph-theoretic algorithm, for which the “comment” might be essentially a short CS paper explaining how the algorithm works, giving its time/space complexity, and proving correctness - the “main function” for simulating a physical or financial system, which might required detailed descriptions of the equations, parameters, and various options I am working on some compiler stuff and have taken to literate programming for basically everything that’s not a simple utility.