3 ms·
> writing explanatory code comments in natural language is seen as unnecessary It IS unnecessary. Having to write a wall of text to explain what your code is d
by omegalulw 5y ago
> writing explanatory code comments in natural language is seen as unnecessary
It IS unnecessary. Having to write a wall of text to explain what your code is doing is one of the simplest code smells.
A little bit of very short comments is ok, but in general any verbose comment should always be for explaining the why, listing out some invariant, etc.
As a side note, another reason not to write comments about what the code is doing is because those comments then need to be updated too - and often they would not be leading to more confusion.
- solatic 5y agoGood documentation explains that which is not naively understandable. Most production-hardened code has lots and lots of code that deals with edge cases. A new employee might look at all the code that deals with the edge cases, think "this is needlessly complicated", and rip it out. Sometimes you can handle this by writing out a test case and document the test case instead. Other times, you can't. It's context-specific.
- sokoloff 5y ago“This algorithm was chosen to ensure compliance with regulation XYZ.” “This planner takes into account inbound logistics delays and temporary out of stock conditions.” I don’t ever want to read a comment like “Adds 1 to x, storing the result in y” but most wall of text comments are describing things that you can’t get from just reading the code.