4 ms·
Code will definitely tell you how something's done with enough energy. It will NEVER tell you WHY everything was done a given way - which is where the comments
by SubuSS 8y ago
Code will definitely tell you how something's done with enough energy.
It will NEVER tell you WHY everything was done a given way - which is where the comments come in. The trick is to keep them updated, versioned and restricted to WHY.
Nothing worse than the template java comments that are filled in for the sake of it. I can't think of any codebase where I was able to reasonably rely on those anyway: except for publicly released API.
- mikhailfranco 8y agoComments also need: The CONTEXT, often non-assertable non-functional assumptions. The WHY NOT, the non-obvious omissions, because code that isn't there cannot be self-documenting.
- pmoriarty 8y agoI try very hard to avoid writing clever code. Instead, I strive for maximum clarity and simplicity. But on rare occasions I do have to write something clever, because the simple and clear thing would either be less efficient, or much much longer, or involve lots of boiler plate code reuse. In those cases I may have to explain not only why I wrote the clever part, but also how it works, because it might not be immediately obvious unless the reader digs really deep in to the code to figure it out. I'd rather save them (or me at a later date) the trouble. Yes, this risks having the documentation drift away from the code if I ever change the code (or if I make a mistake in the documentation), but it's a risk I'm willing to take in small doses.