DEV Community

Discussion on: Self Documenting code isn't

Collapse
 
tinussmit profile image
Tinus Smit

Too often a project / class / method becomes way too cluttered with comments when following this idea of "commenting for the sake of commenting". Any developer worth his / her / their salt can follow a trail of code and infer the logic. You don't need comments to tell you "what" the code does. The code will tell you. Code has to update as requirements change. There's nothing beyond the developer's discipline that compels the developer to update the comments, thus they can't be (solely) relied upon.

I view comments in code (other than the Xml Documentation Comments) as a form of an apology to my future self / other developers. This links nicely to your "why" reasoning. I would have very specific reasons why the code is here / like this. Reasons vary from specific sequence of events to hacks to dealing with very niche scenarios encountered and accounted for. Comments in those instances stand out from the almost boilerplate nature of comments.

Comments linking to issue trackers and the like are not proper code comments, and should rather be check-in comments in your source control repository.

I wouldn't say don't write self-documenting code. I would actually say one should strive to do so. But use a few comments in cases where things aren't as obvious to the observer however many days / weeks / months into the future. And you'll find that people would actually pay heed to those comments, because of their rarity :-)