I’ve been programming for several years now and every time I start to write a line of code, I think about the documentation that I’ll need to write for either people who could read my code later (comments in code) or the users of my program (user documentation). I’ve seen several programmers both in academia and full-time developers that don’t comment their code. I firmly believe in commenting code for several reasons, but I just wanted to point out a couple reasons as well as some methods that I use in my own code commenting.
Commenting for the future
If you don’t comment your code for any other reason, please, please, please, do it for this reason. If you’re part of a large project where you’re constantly updating your code, then this might not be as big of a problem, but if you rarely update your code, you definitely need a record of what things do.
Making sure you comment what things do, what needs to be updated (or fixed), etc. makes life a whole lot easier when you come back to your code down the road. Chances are you’ll be writing so much code that you won’t remember exactly what certain functions do or what a line of code might do.
Another reason to always document code is that you might not be the one working on the same code down the road. Especially if you’re involved in a large project or with a large company. And let’s hope it’s because you were promoted (and not fired for not documenting code 
).
Comment the head of documents
I always comment the head of every document in my program (program files, header files, etc.). I use it as a record of the filename, who initially programmed that particular document, the date of initial programming, and a description of what that file does.
In addition to adding the regular doldrum of information at the head of the document, you could also add licensing information such as copyrights, EULA, etc.
Add a log file at the head of the document
Adding a log file at the beginning of your program files can generally be a good place to store information such as a revision log or changes you’d like to make down the road.
Comment Functions and Class Methods
When you comment functions and class methods you’re making a record of what that particular piece of code does. As mentioned by some of the reasons above, this is a good idea if you’re going to be coming back to your code down the road. Plus, if you have multiple people working on a project, this lets others instantly see what your function or method is doing. Look below to see how I comment functions and methods.
Commenting the head of a document
Below is an example of how I document all of the headings of my program files.
/*
Filename: MyProgram.java
Author: Cory Bohon
Date: Mar-23-2010
Description: This is the most awesome program you'll find anywhere. Srsly.
Version Log:
1.0.1 - Fixed bugs, added awesomeness
1.0 - Initial release to awesomize the world
0.1 - Beta version of awesomeness -- ADD MORE AWESOMENESS
*/
Commenting Functions and Methods
I like to use the Javadoc method of commenting functions and class methods. I even use it for some C++ code that I do, just simply because I think it’s a really efficient way to document functions and methods. Below is an example of this commenting method.
/**
* Returns the my_name variable
* @param none
* @return a string type with the name of the user
*/
string MyProgram::get_name(void)
{
return my_name;
}
I hope this post has helped some people see why it’s important to document your code. If you’re already documenting your code properly, I hope that you have learned some tips from the ways I’m documenting my code. And if you have any tips for me or some tips that I have missed, please leave a comment, or send me a message on Twitter.
