Comment, Please

No, this isn’t a blatantly obvious attempt to generate reader feedback.  This is a look at why developers should use well-commented code throughout their projects and how this seemingly simple addition can change the world–or at least, make people’s lives easier.

What are comments?

//this function does x
or
#this line does y

These lines of text are comments.  They may have slightly different syntax, depending on the language used, but their purpose is the same–to quickly inform those reading the code  exactly those particular lines do.

Why you should comment:

1. It helps other people understand it. This seems like a no-brainer, but you never know when someone else might need to understand your code. If you release the code under certain licenses–GPL, GNU–or another open source, it is important for those who will obtain the source code   to be able to modify and add to the overall functionality of your code.  Even if you aren’t releasing it under an open source license, consider the fact that someone else may eventually have to fix/add to it. I’ve personally have come across some intense code (spread across several dozen files) without any documentation and unraveling how all the pieces fit together took longer than the actual repair.
2. It helps you understand it.Comments can help you quickly troubleshoot an error. You exude a certain confidence when you are able to tell someone “I think I know exactly what’s causing that.”  In addition, you never know when you might have to put down the code and come back to it later.  If you’re looking to extend your code, you can easily remember what everything does and can better integrate any additional functionality.

3. It helps you write better code. After seeing a need for several occurrences of a similar command, you may be able to condense your code as a result of comments.  You also have a chance to logically address and document each step as it occurs, so you may consider errors or other situations that you might not have otherwise.

Well-Commented
The key word here is well-commented. You don’t need to comment every line. In fact, it’s often better if you don’t since comments, as a general rule, shouldn’t match exceed the amount of actual code. Comments should describe the overall functionality of several lines, or help to define variables or cases that otherwise may not be readily apparent to someone reading your code for the first time. You must assume that the reader does have some general knowledge of the language in order to avoid overloading with comments.

//This is a blatantly obvious attempt to generate reader feedback. Please use the following form to share your experience with commented code–or, if you aren’t a developer, a similar experience.

Peter Burgin is a web developer and instructor who’s not afraid of debugging, large textbooks, or speaking in front of huge crowds.

2 replies
  1. Zaid
    Zaid says:

    Well said, I totally agree with you.

    During my previous work, I had to re-design a publishing company website, a website that have a rich index page and over 22 sub-section pages, each have something different. I took me a year to finish and half of that period is to understand the HTML/CSS code, that I am suppose to be expert at!

    However, once I re-designed it, I kept in mind that I will comment each piece of code, to make it easy for the next person. And thats exactly what happened and someone is on control and did the changes within days 🙂

    Nice article and great advice for every designer/developer

Comments are closed.