Ask HN: When is the last time that you heard this red herring?

Documentation of software should show WHY the code is what it is, rather than WHAT it is doing.

The code itself should show what is happening, but not necessarily why it is happening.

If my COBOL taught me anything, it is to always use clear, descriptive variable-names and function-names. Yes it takes more time in typing, but that gets made up in spades in understanding. Especially several months down the track when you're maintaining that code.

Still draw physical logic maps for c++, may be habitual at this point but commenting/documenting has saved me a lot of time by spending fractionally less "extra" time just doing it. Cudos to red herrings and a great Professor in my past. (1)To answer your question directly, more than a decade...