Code comments allow for adding human readable text right next to the code: notes for other developers, and for your future self.
As always, with great power comes great responsibility. Code comments can go wrong in many ways: they may become outdated, silently move away from the code they're referring to, restate the obvious, or just clutter files.
Good Comments
Here are some simple rules to keep your comments helpful:
Avoid stating what some code does – prefer the Why
Some say, perfect code would not need a single comment. That's not entirely true, but their point is valid: comments should not state
what code does. It is another application of the DRY principle: There should be a single source of truth. As the code is capable of expressing what it does, it should not be duplicated in a comment. If the What of some code is not clear, instead of adding a comment, prefer improving the code: use descriptive variable/method names, extract more variables/methods to better describe what is happening, have a simple structure.
However, there are things code cannot express. The best examples are circumstances and motivations. You should in fact leave a comment when some external reason lets you choose uncommon ways, so your colleagues understand why the code looks like it does.
Put comments at the right place
In order to prevent comments from getting mislocated, you should choose the lowest reasonable level in the project hierarchy to put your comment. This will also help your fellow developers to find that information when they're looking for it.
For example, documentation for a bigger concept in the application (like some external API communication) should be put at the main module for that concept. Probably it is a good idea to mention that concept in the project README, but it should direct the reader to the module for details.
In the same manner, internals of that concept (like authentication) should not be described at module level. Prefer commenting the specific piece of code (that does the authentication), be it a method or another class.
Another issue is information from another location. Avoid mentioning "facts" that are defined somewhere else. Although you know your comment is true right now, the developer changing the fact in that other place has no chance of knowing you duplicated it somewhere else in a comment – and your comment will start to lie.
Write robust comments
The more mutable the contents of a comment, the more likely it is to become outdated. In turn, this means if you avoid mentioning mutable things, you have a good chance your comment will be true for a long time.
In order to write a robust comment, try to stay as abstract as the chosen comment position allows. Do not mention implementation details like variable names or algorithms, prefer describing the bigger picture.
Formatting suggestions
In order to give comments a common look and feel, consider these rules:
- Start all comments with a capital letter.
- Put comments right before the code they describe, i.e. method comments should come before the method definition rather than being the first lines of the method body.
- Only use inline comments (at the end of a line of code) if they're real short.
