Do you comment your code?
Now why did he put that extra snippet of code at the end of this function?
How does this subroutine interface with my database?
What was it that I needed to come back and finish in this block code?
You’ve had to ask yourself these questions before if you do not comment your code.
You should always use inline comments when writing your code to avoid those painful questions above. If it is months or years before the code is revisited, will you remember all of the details of why you did what you did?
Well, if you can, your memory is better than mine!
Why inline comments as opposed to taking notes?
Inline comments are great for several reasons.
If you use inline comments instead of other methods, it is easier to keep track of where you actually are in the code. This can serve as a great reminder of what is happening at that specific point in the execution of your function or subroutine.
Here are some examples of how inline comments can be used:
- placeholders for templates
- reminders of database structure for interfacing
- workflow reminders
- bug tracking
- reference pointers
- copyright
- header documentation
If you are working with a team of developers, inline comments can reduce communication errors and improve workflow by keeping everyone on the same page.
If you are working with a third party program to take notes for your code, then you can easily get lost in syntax for larger projects and it can take time to hunt and search.
Worried about bloating code?
Well, this can be an issue if you need to leave alot of comments or you simply want to have your website as slim as can be on the wire (don’t we all want that though?).
An alternative solution might be to include numbered comments that can be used to reference a separate document. Since the other document is detached from the website and is not loaded at runtime, you can feel free to be as detailed as want or need and not lose context. This also keeps your comments private when the code is loaded live or available to the general public.
So how do I comment?
Depends on what programming language you’re using.
Here are some examples:
[HTML] <!-- MULTI-LINE COMMENT HERE --> [CSS] /* MULTI-LINE COMMENT HERE */ [Javascript] // SINGLE-LINE COMMENT GOES HERE [ASP] ' SINGLE LINE COMMENT GOES HERE [php] // THIS IS SINGLE LINE COMMENT # THIS IS ANOTHER SINGLE LINE COMMENT /* THIS IS A MULTI-LINE COMMENT */ [XML] /// SINGLE LINE COMMENT GOES HERE [C#] // SINGLE LINE COMMENT GOES HERE /* BLOCK COMMENT * SHOULD BE AVOIDED IF POSSIBLE */
There are many others out there, I presented the ones I’m more familiar with above. Feel free to add others in comments and I will add them to my list.
Just a few other helpful hints
When writing your comments, it is important to maintain similar structure and readability to lessen frustration for others.
Just get to the point but be clear and concise.
Along those lines, don’t be too verbose with your comments. Only include comments that you think may be useful, which is usually something that is specific to that project.
Consider adding a commented header to some of your documents. When someone adds or edits code, they can leave a timeline with details of what was changed and why for future reference.
// myjsfile.js // Created: 09/20/2009 // Created By: Dale Watkins // Purpose: Form validation and menu effects // // Notes: IDs of form elements to validate: txtEmail, // txtSubject, txtBody // Using Regular Expressions found at // http://regexlib.com // modal dialog box animated by jQuery // (referenced from Google APIs) // if OK will redirect to success.html // // Modified: // Modified By: // Modifications:
As you can see, it contains details of when the file was created, who created it, what it does, and contains room for details of modifications in the future.
Conclusion
To wrap this up, I want to add that commenting is something that can seem a burden when you are working feverishly on a project. But from past experience, I can tell you that having good comments in larger projects can go a long way, even if you are the only code monkey in the mix.
Comment code as you work in it from the beginning while it is fresh and when you look back on it, you’ll be glad you did.
You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.
