Do you comment?

This is a discussion on Do you comment? within the A Brief History of Cprogramming.com forums, part of the Community Boards category; >Well, my script isn't that difficult yet! It doesn't have to be difficult. You might look at it later and ...

  1. #16
    Rabble Rouser Slacker's Avatar
    Join Date
    Dec 2005
    Posts
    116
    >Well, my script isn't that difficult yet!
    It doesn't have to be difficult. You might look at it later and wonder what you were thinking, why you picked that particular solution. Good comments rarely describe the mechanism and more often hint to the reasoning behind the design. It's much more useful to have a look into the programmer's brain than a play by play of what each line of code does. The latter can be figured out fairly easily, but the former is lost when the original programmer can't be found or has forgotten.

  2. #17
    Registered User TactX's Avatar
    Join Date
    Oct 2005
    Location
    Germany.Stuttgart
    Posts
    65
    Quote Originally Posted by PJYelton
    I don't comment, I enjoy the hours of painfully looking at my code trying to figure out my logic from months ago.
    "Weeks of coding can save you hours of planning." :P

  3. #18
    Registered User Jaqui's Avatar
    Join Date
    Feb 2005
    Posts
    416
    Every programmer actually working will be required by the employer to comment.
    so you might as well develop the habit.
    lord knows that every company I've ever talked with has always REQUIRED properly commented code, and they each define properly commented for themselves.

    if you do not comment code, then you do not have a job.
    Quote Originally Posted by Jeff Henager
    If the average user can put a CD in and boot the system and follow the prompts, he can install and use Linux. If he can't do that simple task, he doesn't need to be around technology.

  4. #19
    unleashed alphaoide's Avatar
    Join Date
    Sep 2003
    Posts
    696
    About going back to old code, don't you find class diagram, activity diagram and the like to be useful? If you the original coder, you may know where to find stuff in your code, but for others, do they need to go to source code level to find that this class import that class, this class is derived that class, etc?

    To my (non-professional) experience, I need such higher level documentation more than commenting, especially when most lines of code is self-explanatory/trivial.
    Last edited by alphaoide; 12-28-2005 at 11:20 AM.
    source: compsci textbooks, cboard.cprogramming.com, world wide web, common sense

  5. #20
    the Great ElastoManiac's Avatar
    Join Date
    Nov 2005
    Location
    Republika Srpska - Balkan
    Posts
    377
    This thread is so pointless. I'm sure 99% people would say you should comment. If i was moderator i would lock it.
    lu lu lu I've got some apples lu lu lu You've got some too lu lu lu Let's make some applesauce Take off our clothes and lu lu lu

  6. #21
    It's full of stars adrianxw's Avatar
    Join Date
    Aug 2001
    Posts
    4,831
    >>> If i was moderator i would lock it.

    The thread illustrates some of the reasons why you should comment. Some of these may not be apparent to all members. Yes, 99% of people will comment, but stating the reasons is reason enough to keep the thread.
    Wave upon wave of demented avengers march cheerfully out of obscurity unto the dream.

  7. #22
    Dae
    Dae is offline
    Deprecated Dae's Avatar
    Join Date
    Oct 2004
    Location
    Canada
    Posts
    1,034
    Quote Originally Posted by ElastoManiac
    This thread is so pointless. I'm sure 99% people would say you should comment. If i was moderator i would lock it.
    If I was the moderator I would warn you for pointless posts (sometimes called spam). For example, 3/4 of your posts in this thread. I'm not sure if its from boredom.. but I hear programming is a good hobby.

    >> but I understand my last scipt totaly now,

    Most people do. I completely understand how my program with a bit less than 1000 lines does because it hasn't been a month since I wrote it. When I go back and look at that in 6 months I will have to read a lot of lines of code to understand whats going on again, or I can skip through the commenting to speed up the process. Since I'm the original programmer that could possibly trigger memory of the concept too (which is faster than reading all the code to get an idea). On that note it also varifies the reader has the same idea as the writer. As for other readers its much more helpful because they might not be used to your style of coding, might only need to reuse your code so they just need to know the idea behind it, and of course it helps in many other ways of understanding.

    >> Well, my script isn't that difficult yet!

    I'd say comment a little, but then I wouldn't have followed my own advice. When I was learning to program I barely commented as most of my scripts were less than 50 lines becuase I was just learning and testing. If you're making a game I would say don't worry too much about commenting, as usually people new to programming make some really basic games with way too many lines - like the ones with 500 lines, where only 25 arent cout/cin, switch/if statements, global variables, and pointless/misuse of classes.
    Warning: Have doubt in anything I post.

    GCC 4.5, Boost 1.40, Code::Blocks 8.02, Ubuntu 9.10 010001000110000101100101

  8. #23
    Super Moderator VirtualAce's Avatar
    Join Date
    Aug 2001
    Posts
    9,590
    Yes I do comment. No I'm not really good at knowing when to comment and when not to. Over-commenting makes the code look rather hideous and under-commenting causes it to be nearly unreadable and hard, if not impossible, to follow.

    I comment, but probably not as much as I need to. Perhaps if I actually coded in a dev team with some knowledge about them I would learn to comment much better.

  9. #24
    mov.w #$1337,D0 Jeremy G's Avatar
    Join Date
    Nov 2001
    Posts
    704
    I never comment my code.
    I simply open a source file, use the scroll wheel to skim the entire file and I instantly understand the code part, and the programs entirety even if it's coded in multiple files.


    I'm that amazing.
    c++->visualc++->directx->opengl->c++;
    (it should be realized my posts are all in a light hearted manner. And should not be taken offense to.)

  10. #25
    Registered User
    Join Date
    Dec 2005
    Location
    Canada
    Posts
    267
    Only if Theres lots of code. Even if i comment it, after a month or so i won't understand the comments either

  11. #26
    the hat of redundancy hat nvoigt's Avatar
    Join Date
    Aug 2001
    Location
    Hannover, Germany
    Posts
    3,139
    Well, mostly I comment but I understand my last scipt totaly now, so right now I am to lazy to comment.
    So you wait with commenting until the point where even you don't understand your code anymore ? Just asking because that seems to be my colleagues method.

    I fully understand my code now. It would be pretty sad if I didn't. Anyone else ( including me in 2 months time ) will not have worked with it the last weeks and will have no clue how it works. There can never be too much comment. If someone comes along and can understand it better without any comment, he can delete it to understand the code.

    Good commenting is required by our coding standards at work ( which I wrote ). If you don't keep to the standard, you don't get bonus payments for on-time projects and have to fix it. Sadly, almost every project is considered "urgent" and so the first thing that gets skipped is a proper concept and planning stage and coding standards follow right behind. I think if every single project is considered "urgent" by upper management, upper management has no sense of planning and scheduling itself... but that's a WTF on it's own and not part of this topic.
    hth
    -nv

    She was so Blonde, she spent 20 minutes looking at the orange juice can because it said "Concentrate."

    When in doubt, read the FAQ.
    Then ask a smart question.

  12. #27
    Supermassive black hole cboard_member's Avatar
    Join Date
    Jul 2005
    Posts
    1,709
    No matter how much typing it involves I write a comment header for every function (unless vividly obvious), nothing special, just something along the lines of

    Code:
    /* <func_name>
     *     <purpose>
     * Returns: <values>
     */
    If it's something that doesn't need commenting then I just put "// <func_name>" in case I need to find it later.

    Of course it also depends what language you're programming in. I comment almost every line in assembly programs (usually not mov instructions unless they're a bit vague). I don't go over-board however, like

    Code:
    mov eax, ebx  ; load eax with ebx
    add eax, ecx   ; add ecx to eax
    cmp eax, 0xa  ; compare with 10h
    jz     arse        ; jump to arse if zero
    ; etc
    Then there's that whole argument over what is bad and good commenting over issues in the asm code above, but we could create a whole new thread for that (please don't).
    Good class architecture is not like a Swiss Army Knife; it should be more like a well balanced throwing knife.

    - Mike McShaffry

Page 2 of 2 FirstFirst 12
Popular pages Recent additions subscribe to a feed

Similar Threads

  1. Can someone clarify this comment.
    By Overworked_PhD in forum C Programming
    Replies: 2
    Last Post: 05-15-2007, 10:17 PM
  2. Comment using // or /* &&& */
    By Roaring_Tiger in forum C Programming
    Replies: 3
    Last Post: 03-16-2005, 01:45 PM
  3. Tab->Space converter and comment colorizer
    By Kleid-0 in forum A Brief History of Cprogramming.com
    Replies: 8
    Last Post: 01-30-2005, 04:46 PM
  4. Can someone help me understand this example program
    By Guti14 in forum C Programming
    Replies: 6
    Last Post: 09-06-2004, 12:19 PM
  5. what is a pragma comment?
    By Shadow12345 in forum C++ Programming
    Replies: 9
    Last Post: 11-25-2002, 04:50 AM

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21