Commenting Your Code

Have you even written some code then come back to it a few days or even months or years, and not understand what you were trying to do? This is a part of coding that few people actually practice yet alone try to master.

How should you comment your code? This depends on your style. I personally like to “box” everything in, so that the comments stand out. The issue that some people do not like about this type of commenting is that it makes the code seem longer. I personally think that it makes the code look cleaner.

When should you comment your code? Why should you comment your code? I comment my code before I actually have the code do something. If I am going to make a loop that will have it’s own comment box. If for some reason that I need to make a sudden change in the code or variable that will also get a comment. When making temporary variable, I comment those also.

Is commenting too much a bad thing? As the saying goes “To much of one thing can be bad.”. Don’t comment common programing practices. In JavaScript if you are creating a counter variable, don’t comment that you are creating a counter variable. Instead, in the function you are using it, just state that the variable you are using is for a counter. In CSS, don’t comment why you made a font a certain color. Remember only comment the important part of your code, or parts that you think you or someone else will have issues with in the future.

You maybe saying to yourself, I wrote the code I will know what it does. Before using comments, I thought the same thing, but I can tell you that is not the case. After you deal with a code for a long time you think that you will never forget what each variable does, or how each function or style relates and why you created them. Remember that you will most likely work on other code, which may even use the same variables that you use in other code, which can cause confusion. It also helps if other people have to work with your code to know what you were thinking and why you where thinking it.

Just remember that in CSS you start a comment with /* and end a comment with */. In JavaScript you can use the same method that CSS uses along with double slash (//) to do a single line comment.

Below are some commenting styles you may want to try out and see which one you like the best.

Box Style

//////////////////////////////////
// The Box Style comments where //
// the entire comment is boxed	//
// in.                          //
//////////////////////////////////

/*******************************\
* This is another box style	*
* which creates the similar 	*
* effect of having the comment	*
* boxed in.  Some times the 	*
* asterisk is replaced with a 	*
* pound sign (#).		*
\*******************************/

Multiple Line Comments

/*  This style allows you to
type away with no extra characters to
make the comments stick out.
*/

/* Some people also use this
* style but add an extra character
* at the start of each line.
*/

Single Line Comments

 // Single line comments are used mostly to describe a variable.
cat = brown // describes the color of the cat.

Of course there are other styles of commenting this is just some of the common ones that programmers and designers use.

Topics: Web Development