DZone
Agile Zone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
  • Refcardz
  • Trend Reports
  • Webinars
  • Zones
  • |
    • Agile
    • AI
    • Big Data
    • Cloud
    • Database
    • DevOps
    • Integration
    • IoT
    • Java
    • Microservices
    • Open Source
    • Performance
    • Security
    • Web Dev
DZone > Agile Zone > Four Things to Know when Writing Comments

Four Things to Know when Writing Comments

Stoimen Popov user avatar by
Stoimen Popov
·
Jul. 06, 10 · Agile Zone · News
Like (0)
Save
Tweet
19.37K Views

Join the DZone community and get the full member experience.

Join For Free


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 ;)

code style

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

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • Implementing Microservices Architectures
  • When Disaster Strikes: Production Troubleshooting
  • Getting Started With RSocket Kotlin
  • Chopping the Monolith: The Demo

Comments

Agile Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • MVB Program
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends:

DZone.com is powered by 

AnswerHub logo