Are Comments a Waste of Time?


DevX Home    Today's Headlines   Articles Archive   Tip Bank   Forums   

Page 1 of 2 12 LastLast
Results 1 to 15 of 26

Thread: Are Comments a Waste of Time?

  1. #1
    Glen Kunene Guest

    Are Comments a Waste of Time?

    How useful to you are code comments? Do you write them only out of habit or
    do you believe they serve an important function?

    http://www.java-zone.com/free/articl...Kabutz06-1.asp

    Let us know.

    Glen Kunene
    Senior Editor
    DevX.com



  2. #2
    Prashant Guest

    Re: Are Comments a Waste of Time?

    Hi,
    I think comments play an important role in Explaining code to someone
    who has not written it and it hardly takes any time.When i go through some
    third party code , The comment itself makes it easy to understand the code
    otherwise would be quite a task to understand it.I agree that some comments
    on like get and set methods seems useless , but then it is always good to be
    explicitly mention it.
    Prashant

    "Glen Kunene" <gkunene@devx.com> wrote in message
    news:3c890740$1@10.1.10.29...
    > How useful to you are code comments? Do you write them only out of habit

    or
    > do you believe they serve an important function?
    >
    > http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >
    > Let us know.
    >
    > Glen Kunene
    > Senior Editor
    > DevX.com
    >
    >




  3. #3
    John Butorac Guest

    Re: Are Comments a Waste of Time?

    To understand and be able to maintain code that wasn't written by you, it is
    essential that code is properly documented. I believe that it is arrogant
    to believe that your code is easily understood by all that come after you.
    First, you have no idea of the relative skill level of the developer that
    will come behind you to maintain your code. Second, just b/c it seems
    obvious to you that doesn't necessary mean the logic that you used to tackle
    a particular problem makes sense to others. In my opinion, proper
    documentation doesn't only include comments throughout the code that you
    write, but design documentation that explains to other developers the
    challenges that you faced and the logic that you developed to effectively
    address those issues.


    "Glen Kunene" <gkunene@devx.com> wrote in message
    news:3c890740$1@10.1.10.29...
    > How useful to you are code comments? Do you write them only out of habit

    or
    > do you believe they serve an important function?
    >
    > http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >
    > Let us know.
    >
    > Glen Kunene
    > Senior Editor
    > DevX.com
    >
    >




  4. #4
    Jim Napoleon Guest

    Re: Are Comments a Waste of Time?


    Commented code is very important. The trick is to make the comments precise
    and to the point. I have seen much "commented" code in my years as a software
    developer. The most fustrating to me is to see this large comment at the
    head of a file that goes on and on like a disertation for a thesis and takes
    up half or more of an 8 1/2 by 11 page. I have seen the spectrum of someone
    commenting on every line of code to no comments at all.

    The kind of comments that are very useful are the ones that document what
    the parameters of a function are supposed to mean, and what the local variables
    mean and how they are to be manipulated, and what the return value of the
    function means. The local variables I mean are the non-obvious ones, like
    i,j,k,m,n, etc., which are normally used for indexing something, like an
    array or perhaps a matrix.

    Sometimes the variables themselves can be self-documenting. During one of
    my companies' attempts at ISO9000 certification, a collegue of mine suggested
    that the code itself can meet some of the documentation requirements of ISO9000.
    Variable names like "temperature_at_inlet", rather than just "temperature1"
    can go a long way with understanding the code.

    In closing, always remember and never forget; when you change the code, BE
    SURE TO CHANGE THE COMMENTS ACCORDINGLY. I can't tell you how many times
    I have come across software code with comments that degenerated into a meaningless
    waste of the ASCII code. So that I could understand what the software does,
    I have had to remove these confusing comments, analyse the code (usually
    legacy code that has not been looked at for a while), and put in the comments
    again so that someone else will have a chance of understanding what the code
    does. This is not an efficient use of a developer's time. The kind of comment
    I just love is the kind that is listed at the start of the file with a section
    like "Revision:". At item number 53, it is written; "Made numerous changes
    - by Developer Foo". Looking for Developer Foo's changes is like taking
    a stroll through the Amazon looking for buried treasure with a faded treasure
    map. Not a trail or comment relative to item 53 can be found.

    I could go on and on. All I can say is; be kind to your fellow collegues
    and document properly. If your company has a policy with respect to comments,
    follow them. Otherwise, just use common sense. If you are designing a very
    complicated algorithm, for example, solving Schroedinger's Wave Equations,
    lots of comments would probably be necessary. If you are simply modifying
    a Quicksort algorithm, just a few comments will probably be OK.

    Have a good one.

    Jim

    "Glen Kunene" <gkunene@devx.com> wrote:
    >How useful to you are code comments? Do you write them only out of habit

    or
    >do you believe they serve an important function?
    >
    >http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >
    >Let us know.
    >
    >Glen Kunene
    >Senior Editor
    >DevX.com
    >
    >



  5. #5
    Dtr. Mike Nesel Guest

    Re: Are Comments a Waste of Time?


    Books are a waste of time, too!

    This is so, because I don't like books. They are often so useless that I
    usually don't read them. Ever since my older brother caught me reading Green
    Eggs and Ham as a child and then broke the news to me that it was absolute
    fiction, I've developed a keen distrust of books. This opinion only solidified
    when I pursued my computer science degree. I realized that my classmates
    and I read books only to earn good marks from mean-spirited instructors who
    were more concerned with how many books we read rather than whether or not
    we really understood them! Simply put, I felt that books were a waste of
    time.

    Dtr. Mike Nesel, PhDSt, MDD, MsS, FS



  6. #6
    Paul Clapham Guest

    Re: Are Comments a Waste of Time?

    I usually don't write many comments, on the theory that the code should
    explain itself. And most code does. However, when I find myself writing
    ugly or convoluted code, I also find myself writing comments to explain it
    (and to apologize for it). Or -- as Dr. Kabutz alludes to -- if I have
    unfinished business, I'll make a note in the code.

    I have recently been working on some code that I wrote several months ago --
    uncommented, of course -- and finding it difficult to maintain. But
    thinking about comments in that context, I realize that the comments that I
    and most other programmers would have written would have been of little use.
    I had questions like "why does this class have a remove() method and a
    close() method, what's the difference, and which should I modify?" I would
    bet that the comments you would have found written by someone who believed
    in them would have said something like this:

    public void close()
    /** Closes the component by making it invisible **/

    public void remove()
    /** Removes the component from the tree of displayable panels **/

    No hint of why they are separate methods or which you should override if you
    want to have something cleaned up when the system is finished with the
    component. But of course the design is documented somewhere else, isn't it?



  7. #7
    Tracy Barlow Guest

    Re: Are Comments a Waste of Time?


    "Glen Kunene" <gkunene@devx.com> wrote:
    >How useful to you are code comments? Do you write them only out of habit

    or
    >do you believe they serve an important function?
    >
    >http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >
    >Let us know.
    >
    >Glen Kunene
    >Senior Editor
    >DevX.com
    >
    >


    I've been a programmer for 23 years, I started with COBOL and BASIC, and
    now develop mostly in VB. I find, in most cases, that if I am having trouble
    working out what's going on by reading the code, then the comments rarely
    if ever shed any light on the it.

    I was taught, as a COBOL programmer, to make my code self documenting, using
    variable names etc that described their purpose. So I rarely use comments.

    In my opinion Tutors, lecturers, teachers of computer science, who insist
    on extensive comments within the code are out of touch with the reality programming.




  8. #8
    David D. Cruger Guest

    Re: Are Comments a Waste of Time?


    Mr Kunene is so way off base it's unbelievable. I have been programming for
    the past 18 years and the one absolute thing I have learned is that comments
    can save you time, BIG TIME. Trying to figure out what is suppose to happened
    in a block of code that was written 8 years ago that doesn't have comments
    can be a mind bending experience. Even code you wrote your self. Why the
    heck did I do that?

    I believe a better statement to make about comments is this: I don't hate
    comments I hate bad comments. You can apply the same statement to code:
    I don't hate code I just had bad code.

    Comments are not just used to indicate what a certain function does but a
    function comment header can give details about code migration. Modify dates,
    by whom and why, bugs that might have been fixed. These are very valuable
    pieces of information. Comments, well formatted ones, can also help break
    up code to make it more readable. Then you have module headers to indicate
    what the class or module is going to do...etc

    With all that being said I can make this statement. Good code can stand
    somewhat on its own with out comments. However even slightly bad code I
    would prefer to even have bad comments than none at all.

    Keep the comments going.

    David D. Cruger


  9. #9
    David Browning Guest

    Re: Are Comments a Waste of Time?


    "Glen Kunene" <gkunene@devx.com> wrote:
    >How useful to you are code comments? Do you write them only out of habit

    or
    >do you believe they serve an important function?
    >
    >http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >
    >Let us know.


    I have to agree with Dr Kabutz. choosing sensible, descriptive names (ie
    which capture the purpose of the method or variable) pretty well negates
    the reason for comments. Programs can be almost self-documenting. It reduces
    the amount of 'typing' significantly; makes maintenance much easier and helps
    to focus on each method doing only one thing.

    When I'm faced with maintaining commented code, I usually find it necessary
    to change method/variable names to encapsulate the description in the comment,
    simply to be able to understand the code!


  10. #10
    David Salahi Guest

    Re: Are Comments a Waste of Time?


    "Glen Kunene" <gkunene@devx.com> wrote:
    >How useful to you are code comments? Do you write them only out of habit

    or
    >do you believe they serve an important function?
    >
    >http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >
    >Let us know.
    >
    >Glen Kunene
    >Senior Editor
    >DevX.com
    >
    >


    Dr. Kabutz' article on comments was a fairly snide attack on a straw man.
    Of course, no one is interested in reading inane comments or comments which
    are so obvious they could have been generated by a wizard.

    But what about well-written comments? Maybe the problem is that so few programmers
    write good comments that Dr. Kabutz has rarely seen any well-written comments.
    I think that more emphasis needs to be placed on teaching programmers how
    to write good comments.

    Personally, I do write comments and as time goes by (25 years in this business
    now), I continue to become more convinced of the value of good comments.


    For example, what a function does is often different than how it does it.
    One good use of comments is to document the overall purpose of a function.
    Often, it's difficult to tell what a function is actually accomplishing by
    wading through the individual lines of code.

    Comments can also be very valuable in giving context. I.e., it may be helpful
    to explain how a particular function fits into the big picture, when it is
    called, what the end-user is trying to accomplish at that time, what the
    data should look like, etc.

    Another good purpose of comments is to save time. Instead of spending five
    minutes studying a function, I could spend 15 seconds reading a comment.


    Kabutz makes one good point, though: make code self-documenting as much as
    possible and you will reduce the need to write and maintain comments.

  11. #11
    Russell P. Holsclaw Guest

    Re: Are Comments a Waste of Time?

    I found the article very unconvincing. Although it's true that bad comments
    are sometimes worse than no comments at all, sometimes things need
    explanation.

    In the examples given in the article, it occurred to me on reading it that
    the code in the getName() method was simply a "placeholder", or "stub
    procedure" to be replaced at some future time by a method that actually
    returned a real name, instead of an uninformative message.

    In a sense, however, what comments there were helped me to realize that,
    although they should have said so explicitly. Obviously, the author of the
    article didn't pick up on that at all, or he would have mentioned this.

    In my own experience as a programmer, I've found that the best approach to
    commenting is to pretend you are explaining the code to someone who's
    looking over your shoulder at it, (perhaps someone who's going to take over
    the code as soon as you go outside and get run over by a bakery truck) and
    write into the comments whatever you would have told that person.

    [I think the parody of the article written by "Dtr Mike Nesel" pretty well
    captured my own gut reaction to the article. It was an exercise in
    arrogance. I was expecting to read an extensive treatise on the difficulties
    of maintaining sync between code and comments, but the article turned out to
    be completely devoid of such subtlety. Publishing it was a poor editorial
    decision, perhaps influenced too heavily by the author's advanced degree.]

    --
    Russ Holsclaw


  12. #12
    N Nguyen Guest

    Re: Are Comments a Waste of Time?


    "Glen Kunene" <gkunene@devx.com> wrote:
    >How useful to you are code comments? Do you write them only out of habit

    or
    >do you believe they serve an important function?
    >
    >http://www.java-zone.com/free/articl...Kabutz06-1.asp
    >
    >Let us know.
    >
    >Glen Kunene
    >Senior Editor
    >DevX.com
    >
    >


    This article is what an arrogant nonsense opinion on programming would be
    like. As for the author, I would urge him to go to www.literateprogramming.com
    to read Knuth’s thinking about commenting code.

    From the NW.



  13. #13
    Mike Stillman Guest

    Re: Are Comments a Waste of Time?


    Some thoughts from a Sr. Technical Writer at a major
    Web software company:

    * Amazing Andrea won't always write the code for the
    ScheduleWizard 3000's autocomplete feature. She could
    move onto another module, project, company, or, as
    another poster said, get hit by a bakery truck. At some
    point, someone else, not necessarily a programmer, will
    likely have to work with this code. Sensibly named
    variables and well written comments will be essential for
    that person.

    * Sure, some uncommented code requires minimal time to
    understand. However, if the developer invests a small
    percentage of the time writing good comments, this should
    be a great ROI in time saved for others.

    * Sometimes good coders don't make good writers, and vice
    versa.

    * Hmm, maybe I should develop a course on Code Commenting!

  14. #14
    Steve Schmitt Guest

    Re: Are Comments a Waste of Time?


    No, comments are not a waste of time - if they are meaningful. Mr. Kabuts
    is correct that many comments are written just to make the code look commented.
    But sometimes they can be benificial.

    For example, if your method returns a collection, the method signature doesn't
    tell anyone what's inside. So you might have a JavaDoc comment like this:
    <code>
    /** Returns an ArrayList of HashMaps that defines the presentation.
    * Each HashMap contains PresentationWidget objects, keyed by the
    * Integer presentationAreaId
    */
    </code>
    This reveals the otherwise obscure contents of the returned ArrayList.

    Inline comments are often useless, if they simply echo what the code is doing.
    The classic useless inline comment something like this:
    <code>
    packet += 2; // increment packet by 2
    </code>
    Thank you, Mr. Programmer, we know what the += operator does! But if the
    comment tells us <b>why</b> we're doing that, it might be useful:
    <code>
    packet += 2; // skip odd packets, since they contain useless spaces
    </code>

    If someone is using a class you have written, good comments can help them
    use it properly. If someone is modifying a class you have written, good
    comments can keep them from screwing it up. Think about this, and only write
    comments that will actual be useful.


  15. #15
    CliffordEW Guest

    Re: Are Comments a Waste of Time?


    I am sharing this article with my class on "Application Programming". I am
    one of those "mean-spririted" teachers that require too many comments. His
    second bulleted reason for disliking comments is very good. It is a mistake
    to write comments that tell what the code does. The code itself must be
    written to tell the reader what the code does. If it doesn't the code needs
    to be rewritten. Good, worthwhile comments tell why the code does what it
    does. And sometimes, they tell what the code ought to do, but doesn't yet.
    But in that case the code should be changed. Not left wrong through release
    after release.

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •  
HTML5 Development Center
 
 
FAQ
Latest Articles
Java
.NET
XML
Database
Enterprise
Questions? Contact us.
C++
Web Development
Wireless
Latest Tips
Open Source


   Development Centers

   -- Android Development Center
   -- Cloud Development Project Center
   -- HTML5 Development Center
   -- Windows Mobile Development Center