Professional Documents
Culture Documents
Tips To Comment The Code
Tips To Comment The Code
Tips To Comment The Code
www.softheme.com
1. Comment each level
Comment each code block, using a uniform approach for each level. For example:
• For each class, include a brief description, author and date of last modification
• For each method, include a description of its purpose, functions, parameters and
results
Break code blocks into multiple “paragraphs” that each perform a single task, then
add a comment at the beginning of each block to instruct the reader on what is
about to happen.
For multiple lines of code with trailing comments, align the comments so they will
be easy to read.
Some developers use tabs to align comments, while others use spaces. Because
tab stops can vary among editors and IDEs, the best approach is to use spaces.
if (a == 5) // if a equals 5
counter = 0; // set the counter to zero
This wastes your time writing needless comments and distracts the reader with details
that can be easily deduced from the code.
Avoid rude comments like, “Notice the stupid user has entered a negative number,”
or “This fixes the side effect produced by the pathetically inept implementation of
the initial developer.” Such comments do not reflect well upon their author, and
you never know who may read these comments in the future: your boss, a
customer, or the pathetically inept developer you just insulted.
Don’t write more in comments than is needed to convey the idea. Avoid ASCII art,
jokes, poetry and hyperverbosity. In short, keep the comments simple and direct.
Tag comments don’t explain code; rather they seek attention or deliver a
message. But if you use this technique, remember to follow up and actually do what
the message is asking.
Add comments while you write code and it’s fresh in your memory. If you leave
comments until the end, it will take you twice as long, if you do it at all. “I have no
time to comment,” “I’m in a hurry,” and “The project is delayed” are all simply
excuses to avoid documenting your code. Some developers believe you should
write comments before code as a way to plan out your ultimate solution. For
example:
When it comes to commenting code, think not only about the developers who will
maintain your code in the future, but also think about yourself. In the words of the
great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that
piece of code.”
As a result, we ourselves will be the first beneficiaries (or victims) of our good (or
bad) comments.
There is no point in commenting correctly on code if the comments are not changed
with the code. Both code and comments must move in parallel, otherwise the
comments will actually make life more difficult for developers who maintain your
code. Pay special attention to refactoring tools that automatically update code but
leave comments unchanged and hence obsolete in the same instant.
One of the basic principles for many developers: Let your code speak for itself. Although one
suspects this movement is led by programmers who do not like to write comments, it is true
that self-explanatory code can go a long way toward making code that’s easier to understand
and can even render comments unnecessary. For example, the code in my Fluid Interfaces
article shows how clear self-explanatory code can be:
In this example, comments are not needed and would likely violate tip #4. To facilitate
readable code, you might consider using proper names (as described in the classic Ottinger’s
Rules), ensure correct indentation, and adopt coding style guides. Failure to comply with this
tip may result in comments that seem to apologize for bad code.
Although tip #10 shows how we ourselves benefit immediately from good
comments, these tips will benefit all developers, especially in the context of team
working together. Therefore, feel free to share these commenting tips with your
colleagues to create code that is easier to understand and maintain.
Questions? → info@softheme.com