Poll: Do you comment your code?
Thursday June 7, 2007
Commenting your code can mean the difference between a maintainable design and complete chaos, but if you're not in the habit of using comments they can be easy to forget.
Comments can be very useful to help you in the future - even if you're the only developer working on the pages. IE 6 and below have conditional comments to hide things from specific browser versions. You can also put comments in CSS. But some people don't like to use comments because they can slow pages down.
Do you comment your code?
- Vote Now
- Yes, I comment all over my code
- Yes, every page has at least one comment
- Yes, periodically, when it's absolutely required
- No, I forget to comment
- No, comments slow down pages too much
- No, I don't know how to add comments
- No, for some other reason
I've noticed, using Dreamweaver, that I don't put as many comments in my code when I'm in WYSIWYG mode. I have the comments turned on, but I just forget to add them. Have you had a situation where comments were a huge help? Or if you refuse to use comments, why do you hate them?
Comments
One of the best things about comments is separating sections of the code/HTML so that scanning the page to find places where frequent updates are made. I like to use extra spaces around the comments, and try to standardize the phrases in some areas so it’s easy to scroll down and spot, or do a search for a particular strip of code/HTML. I guess you can say that I use them for pointers as well as descriptions.
I used to comment everything back in the days when I hand-bombed code using a text editor. These days Dreamweaver (et al) makes commenting less critical in my markup. These days my commenting is limited to PHP code and some CSS rather than the semantically simple XHMTL.
HTML is amazingly simple stuff, even at its most complex. After you’ve been at it for a while, you should be able to read HTML without comments. Even CSS is simple enough that a quick eyeball-scan will tell you what’s happening.
Not that I follow my rules all the time. If the page is content-dense, I’ll put comments in to mark a section break, e.g., “Start Left Column”, “End Left Column”, etc. There are always exceptions.
Other than that, comments are important with programming languages like PHP, where you need to document WHY you’re doing something, and maybe WHAT you’re doing. The time may come when you aren’t the person managing the code, or maybe the code is being maintained by team of developers. Comments help immensely in those situations.
But comments in HTML? That’s pretty bizarre.
WebSlinger: I had to laugh when I read your comment “Even CSS is simple enough that a quick eyeball-scan will tell you what’s happening.”
You’ve clearly never developed a CSS based corporate Web site with hundreds of thousands of pages. At one point we had something like 5 separate CSS files, each one had several thousand lines of CSS. Trying to figure out what was causing an image to be moved over 3 pixels from it’s correct location could be a 2-hour task for my developers. And correcting it, without breaking other parts of the site, could be another 2-4 hours on top of that.
I agree that CSS on a line-by-line basis it should be clear, but the bigger and more complex things get the more confused it is.
Jennifer. Actually I have created such sites. I’ve been online full-time for over 20 years, and have developed hundreds of sites over the last 13 years. I’m a real programmer with over 30 years of experience. If CSS is difficult for you, so be it. I have no such problem.
Hi WebSlinger, I didn’t say that CSS was difficult, I said that it’s not always possible to do a “quick eyeball-scan” and determine what is happening with the CSS.
Webslinger…In the interests of honest advertising, I hope your business card reads “arrogant programmer”.
Thanks Jennifer, for some really helpful stuff. I really like your systematic approach which manages to avoid erring on the side of too much high-tech jargon. As an average having-a-go mug punter, I have learned heaps from you over the months.
Regards, Brian,
Hervey Bay,
Queensland, Australia
I agree with most of you here. Comments really aren’t needed unless you are using a programming language. Markup languages are simple enough not to require it.
I always comment my javascript and asp code though.
I must ammend my comment, there are exceptions for really large CSS files, and probably for HTML if you actually wrote extremely large blocks at a time. However I never find myself writing very big chunks of html as it’s inside of my serverside code functions.
Not arrogant at all, Brian. I’ve been around the block a few times more than most. That’s all.
There’s nothing arrogant about experience and what it brings. When you have some you’ll understand.
Honest Advertising: Claiming that you can do things others can’t, and backing up that claim on a daily basis.
Brian, attention to detail is an important skill. You seem to have missed the part where I said “there are always exceptions”. Thousand-line CSS files are exceptions. I’ll bet if I had a wack at one of those, I’d find that 20% of those lines are either empty, or comments. Another 20%-25% would be redundant or unnecessary code.
How do I know? I’ve done it. You?
I have to agree that WebSlinger has been around for 20 years. In fact, the source code on his website is from 20 years ago. Still using HTML 4.0, deprecated tags, and miles of tables for layouts. Not only that, but the testimonials section is just hilarious.
Besides, if he’s good enough to do without comments, why even bother with the ones on this site?
Nice try, beginner. The underlying PHP code is well beyond your capabilities, but since you’re a beginner, you wouldn’t understand. You weren’t doing this 20 years ago, or you’d know that HTML didn’t look like this back then.
BTW, comments do NOT slow down loading… unless you’re writing a book inside the comment tags.
ASCII transfers very quickly, and is the first thing downloaded when a page is loaded. The images come second. If you want to speed up transfers & page loads, use smaller & fewer graphics on the page(s).
I need to apologize for my overly harsh tone on this forum. I don’t know what got into me. That’s not me at all. Seriously.
I don’t comment out because I’m too scared about triggering an IE bug that displaces some text under certain conditions when the CSS has comments.