No comments, EVER!
Comments in code is a thing of the past
Don’t we cringe a little every time we come across a method, or a function, or a class that has a lengthy, freestyle comment above it? Well, the reason for that is that most of those lengthy comments are:
- A sign that the code below it is a mess;
- Have little to no connection to the code below it (out of sync, not maintained well);
- An exact copy of the code below it, just worded “more naturally” (time wasters);
Comments get out of date really fast! It’s a chore to maintain them, it’s a chore writing them, and you are discouraging readability (and, as a consequence, maintainability) by allowing them!
If I need to read your comment in order to understand your code, there is something wrong with your code.
So what’s the alternative? The alternative is to promote readability. Code should document itself. It’s incomparably better to follow natural language conventions when using high-level programming-language constructs while in process of creating an app, or a feature, or fixing a bug.
When writing code, a computational instruction, you are not only responsible for communicating this instruction clearly to a computer but also responsible for communicating this instruction to current/future maintainers. We are not in a bubble anymore, globalization is a thing now, impossible to grow (individually, and as a team/org) without proper, code-level communication.
And, of course, there are some exceptions.
For example, a comment can be useful if it explains a choice of an algorithm, a reasoning behind this particular implementation of an algorithm, why this decision is important.
Generally, comments can answer one of the two questions: “What?” and “Why?”. “What does the code below do?” and “Why does the code below exist?”. Comments that answer the “Why?” question are acceptable, comments that answer “What?” question are not acceptable, under any circumstances.
Again, refer to your best judgement when making a decision.
What about API docs and alike?
API docs is a necessity! Can’t have API’s without documentation, and even in this case you should never write comments yourself. API documentation should be auto-generated based on your code.
You should be able to generate Swagger style docs without writing a single line of a comment yourself.
The perfect API generation setup: readable code written with strictly typed language. Modern generators should be able to parse variable/method/function names written with CamelCase or snake_case and translate it into readable documentation (similar to how GitHub does it with branch names when creating PRs with multiple commits).
In conclusion.
Communicate with your code (not comments), communicate with code-reviews, invest the internal (individual) resources you allocated for comments into improving readability of the code itself. This investment will payoff in the future.
P.S.
Have you ever seen a job post that has “writing well commented code” in Job Responsibilities section? Well, that’s a red flag! You’re welcome.
P.P.S
Funny but relevant comments are also acceptable. Software development doesn’t have to be dry and boring. We are all humans after all.
