Say hello to your friend, the comment.
// Comments will make your life a lot easier.
/*
Don’t be afraid to use a lot of comments.
They can only help.
*/
I know writing comments is extra work. For those of use who don’t have perfect typewriting skills (and with the QWERTY keyboard, who does?). But they are extremely valuable.
(Zemanta tells me that I should add this link: 7 Reasons to Switch to the Dvorak Keyboard Layout. Personally, I’d prefer the Programmer’s Dvorak, if I can ever set up Ukelele to work properly. Who knows what I’m talking about???)
I write convoluted code. I have a hard time following MVC. It’s a fact of life. I easy this problem significantly by using comments. Trust me—I was skeptical about comments. Why should I write comments? I know what my code does! Uh…no I don’t. It’s a simple fact of a programmer’s life that we start to forget about what our code does. Or why that code works the way it does. By adding comments at the beginning of every few lines, or even a few tabs away from the end of every other line, it makes my job so much easier.
Trust me. Comments are worth the extra effort.
Etresoft
/ August 29, 2010One last “comment” for today. Don’t over comment. Most programmers spend all their commenting time on only the useless comments. Most function header comments are useless. They just list the function name, arguments, and what the function should do. Well, the function name and comments are right there. The name should tell you what it is doing. And if you ever need to re-factor or re-architect, all those comments must be re-done.
Personally, I like to wait 3 days before writing comments. If the code has been running for 3 days, it is probably not going to change much. By then, I have started to forget what the code is doing, but can still remember it once I study it briefly. The harder I have to work to figure out what I did three days ago, the more that section of code needs a comment.
inspire48
/ August 29, 2010You probably know better than me, but I’d like to respectfully disagree—to an extent.
For me, I find that I tend to write methods that end up going outside the original intent—and then, as a lazy programmer, I don’t want to go back and edit the method name, especially if it’s already been called. Give it a week or two, and then I forget what the method does. Also, as the nature of most software, especially in the early development phase, is to get as far ahead as you can, and get the project off the ground, I don’t necessary want to go back 3 days later.
My take is that useless comments are better than no comments. Of course, there is such a thing as over-commenting, but I define that based on how much time you spend commenting, versus actual coding…I do comment on arguments and function functionality—if they need explanation. But if you write something, comment it to mean something different (hopefully only slightly different), then that’s a sign that the method may need to be re-worked…
I suppose my argument isn’t as solid as it could be. Comments are a subject that is more of a matter of personal preference. You never know when you’ll meet a guy who can memorize his entire code library over a couple decades’ work…
