Hacker News new | ask | show | jobs
by persona_reuse 1066 days ago
One can figure out 'how' and 'what' from the code, given enough time. The most valuable thing in code is the brain of the Past Person who wrote it, looming over your shoulder, telling you 'why' in very explicit terms.

That 'why' also helps to show that Past You knew wtf you were doing, and lets Present You feel confident in making changes, because you know what the intent was.

"I'll remember this!" is one of the greatest lies in CS.
1 comments
quectophoton 1066 days ago
Yeah when I find myself wanting to write a comment that describes the implementation, I usually end up writing a test where possible.

I'm trying to think, but I can't come up with any kind of comment that has been useful that didn't have a "because" word, explicitly or implied.

Like, even if there's a comment like:

"This function only queries X and Y fields. Don't add more. If you need more than that, use this_other_function instead."

It has an implied reason behind it, and the mistake is not adding that reason to the comment. So this comment would be missing something like

"[...] because this is being used in a critical part of the code that is very nitpicky and it's very difficult to test because requires some annoying manual steps", or something like that.

There are probably situations where a "what" or "how" comment really are better than "self-documenting code" though. I would probably appreciate those comments if I ever need to read branchless code, SIMD code, or similar performance-sensitve witchcraft.

link
a_e_k 1066 days ago
> I would probably appreciate those comments if I ever need to read branchless code, SIMD code, or similar performance-sensitve witchcraft.

I've done this before in production code. One of my only exceptions to my policy against leaving in commented-out code has been things liking leaving the unoptimized serial code commented out at the top of a section of some hand-vectorized code full of SIMD intrinsic. It clearly showed the intended "what", but was also useful to keep around as a baseline for performance testing and reference code to compare against for debugging.

link