3 ms·

I prefer comments in the code (or tests) to explain the "why" of the code to external systems. I want someone to get the "why" even if they get my code from a t

I prefer comments in the code (or tests) to explain the "why" of the code to external systems. I want someone to get the "why" even if they get my code from a tarball, an e-mailed diff, or if some asshole overwrote commit messages for some fool reason. For my part I don't want to have to switch contexts to go hunt through an issue tracker or commit messages to know why someone did something. I have other shit I need to get done. I don't want someone reading my code, with their own work to get done, wasting their time hunting for my reasoning why I put "pi = 3". I want to be helpful to future victi...maintainers of my code[0]. [0] https://groups.google.com/d/msg/comp.lang.c++/rYCO5yn4lXw/oITtSkZOtoUJ https://groups.google.com/d/msg/comp.lang.c++/rYCO5yn4lXw/oI...

kevin_nisbet 6y ago
Yea, this frustrates me endlessly working in a code base that has the philosophy of no comments is better than bad comments, and as such code should be self describing with no comments. "Self documenting" code only describes what is happening, doesn't explain why the code exists, what problems are being tackled, bugs fixed, etc. Makes it very easy to lose behaviours, because it's easy to delete or change behaviour when we don't know why it exists. I sort of think it's common to accidentally comment what is happening, those comments to get out of sync with the code and be otherwise unhelpful, which leads to this overreaction towards self documenting code and having policies limiting comments.