Advertisements

Comments are Important


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.

Advertisements
Leave a comment

3 Comments

  1. Etresoft

     /  August 29, 2010

    One 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.

    Reply
    • You 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…

      🙂

      Reply
  1. Objective-C Lesson 1: Hello World! « Programming for iOS

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

Advertisements
  • Welcome

    My goal is to make CupsOfCocoa into a beautiful source for beginners to the iPhone platform to get started. Subscribe below for more, and stay tuned!

  • Contact Me

    If you need to contact me for any reason, feel free to send me an email.
  • The Giving Spirit

    If you've found this site helpful, would you consider donating a little sum? Any amount is appreciated...Thanks so much!

  • Roadmap

  • Enter your email address to follow this blog and receive notifications of new posts by email.

    Join 222 other followers

  • Back to the Past

    August 2010
    S M T W T F S
        Sep »
    1234567
    891011121314
    15161718192021
    22232425262728
    293031  
  • Time Machine

  • You count!

    • 621,851 views
  • Worldwide Stats

    free counters
  • Advertisements
%d bloggers like this: