5 ms·
Like what? It can’t be the “how” - the code should be able to express that clearly. It can’t be the “what”, again that should be apparent from some combination
by CraigJPerry 7y ago
Like what? It can’t be the “how” - the code should be able to express that clearly. It can’t be the “what”, again that should be apparent from some combination of code and configuration / metadata.
So that leaves the “why”. To my mind, code comments are the worst place to record why a particular implementation exists. The why often needs collaboration with non-coders.
- artsyca 7y agoIt's definitely the why for any particular unorthodox bits like shims hacks workarounds and the like The worst is finding some snippet from stack overflow or GitHub without a reference to the issue to back up why this thing is here or perhaps a TODO: with an improvement
- minaa-chan 7y agoI disagree. The code is the best place to comment the why. Regardless of what is documented or what is written up on jira or w/e, the code is what is true. Commenting the purpose of the code and maybe a link to some documentation allows a future reader to see if the code still fulfills the requirements.
- CraigJPerry 7y agoThe comments are very often not true, that's why there's so much push back
- minaa-chan 7y agoSo they should be updated the same as any other documentation. They're there to help. They don't need to be 100% infallible to be useful.