Most developers I know say: don’t write any comments, because they are evil and little puppies will dye if you do.
The arguments they give:
- code comments will get out of date
- code should be self explaining.
I totally agree, but there are counter arguments, to write comments:
Code comments out of date?
If you look at the AngularJS code, the comments are used to generate the documentation on the site, so when the comments are not updated, the documentation on the site will be outdated. This is one trick to keep your comments up to date.
Code should be self explaining
I totally agree, code should be self explaining!
But it’s not the problem, that code comments are written, but the way they are written.
The most comments explains what the code does, not why. I do not care, “what” the code does, I want to know “why” it is written and “why” it is written in the manner it is written.
I recently had to make changes to C# code that was written ages ago (13 months in this case). I red the code and the “WTF counts per minute” started to pile up. I red the code comments and they exactly explained what the code did, but I am an experienced C# developer, I know what the code does, because I can read C#, but I did not understand why the code was written and why it was written in the way it was written.
So I checked source control to find this “terrible” developer that had written this code to ask him, what on earth he was thinking and as you will probably expect it was me, myself and I, 13 months ago .
So please, if you write inline comments, don’t write “what the code does”, write “why” the code is written and “why” you write it in the way it is written”.