Member-only story
15 Rules for Writing Clean Comments
Common pitfalls to avoid as a programmer
Comments in code have been there since the beginning of programming. But in today’s world, do we need them? Some would argue that we shouldn’t have comments in our code at all.
Well, it’s true. Code should be self-documenting. But still, there are some instances when we need to add comments. About this Uncle Bob says,
“Comments are an unfortunate necessity, not great achievements.”
Today, we’ll look at some rules to follow and the common pitfalls to avoid while programming.
1. Multiline Comment vs. Single-Line Comment
Whenever possible, try to write long comments as multiline comments.
The following comment is bad:
Instead, do this:
2. Nonlocal Comment
Here’s an example of bad comment. The default time out is 5000, but it doesn’t specify where this value was set.
Never comment about some code that’s not present. Instead, try to provide some context.
