Over a million developers have joined DZone.

Four Things to Know when Writing Comments

· Agile Zone

Learn more about how DevOps teams must adopt a more agile development process, working in parallel instead of waiting on other teams to finish their components or for resources to become available, brought to you in partnership with CA Technologies.



Every developer has been learned from his teachers how important is to comment his source code. You should comment the classes, the methods, the logic, etc. However nobody explained how exactly to code with comments between the lines. Have you ever seen that

i++; // we increment i with one

That’s a shame! This doesn’t tell you anything, and what will happen if sometime later somebody sits in front of that code? He’d be amazed!

How To

In fact the task is not to determine what are the bad parts of not commenting the code, but how to overcome this. How to write comments. Here are some basic advices.


1. Think about the other developers

First of all the most important thing is to write comments with other programmers in mind. They should understand the logic of your code from your comments and not from the code itself.

2. Write in English

Even you’re not a native English speaker, and you English is not so good, it’s a must to write in English. This is really important when you work for a open source project when always there’s a big community around the project, you cannot be sure that everybody understands your language.

I know that this is difficult – also for me the English is not my native language, but that’s really a must. Once you start doing it, you’ll see that it’s not so difficult.

3. Comment the methods as a black box

Don’t write in a method comment what technique is used to achieve the result. It’s good to describe what the method does, not how it does it.

Bad example:

/**
* returns $a + $b
*/
public function sum($a, $b)
{
return $a + $b;
}

Better:

/**
* Returns the sum of two numbers
*
* @param number $a
* @param number $b
* @returns number $a + $b
*/
public function sum($a, $b)
{
return $a + $b;
}

4. Comment the logic, not the technical solution

When there’s a loop or a statement it’s useless to describe that this is a loop or statement, isn’t it? A better approach is to describe in a comment why you needed to implement this logic in such way.

Wrong:

...
$arr = array();
$i = 0;

// in a while loop we
// initialize every element with 0
while ($i < 100) {
$arr[$i++] = 0;
}
...

Better:

...
$arr = array();
$i = 0;

// we initialize an array of 0s
// to store the sorted elements
// on the first pass... etc, etc.
while ($i < 100) {
$arr[$i++] = 0;
}
...

Conclusion

In fact the most important thing is to write comments with other developers in mind. Tell the future developer of that code what’s in the code, and pray for mercy ;)

Discover the warning signs of DevOps Dysfunction and learn how to get back on the right track, brought to you in partnership with CA Technologies.

Topics:

Published at DZone with permission of Stoimen Popov, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}