how to properly comment on c code

This is a discussion on how to properly comment on c code within the C Programming forums, part of the General Programming Boards category; hey guys, i need to put comments in my code and was wondering whether there are like guidelines or dos ...

  1. #1
    Registered User
    Join Date
    Dec 2007
    Posts
    67

    how to properly comment on c code

    hey guys, i need to put comments in my code and was wondering whether there are like guidelines or dos and don'ts of code commenting. I need some tips on how to properly comment the code.
    thanks

  2. #2
    Frequently Quite Prolix dwks's Avatar
    Join Date
    Apr 2005
    Location
    Canada
    Posts
    8,046
    Some personal guidelines I like to follow:
    • If it's concise code, don't put a comment in. I've seen too much code that looks like this:
      Code:
      int i; /* declare i to be of type int */
      scanf("%d", &i);  /* read i from the user */
      i ++;  /* increment i */
    • Always document what a function does, and data structures too. If you want to, consider using a documentation tool like Doxygen, which can extract information from comments with special symbols to generate documentation for you. This is very, very useful.
    • Try to be consistent. I hate it when code has comments like
      Code:
      // hello, world
      // Hello, world
      /* Hello, world. */
      /* Hello, Grand World. */
      
      /* yes,
      indeed. */
      
      /* yes,
          indeed. */
      
      /* yes,
       * indeed. */
      
      /*------*\
       | yes. |
      \*------*/
      (I hate capitals especially, but Let's Not Go There.)

      In other words: use periods and capitals consistently (or at least not randomly), and consider not using random mixes of single-line and multiline comments.
    dwk

    Seek and ye shall find. quaere et invenies.

    "Simplicity does not precede complexity, but follows it." -- Alan Perlis
    "Testing can only prove the presence of bugs, not their absence." -- Edsger Dijkstra
    "The only real mistake is the one from which we learn nothing." -- John Powell


    Other boards: DaniWeb, TPS
    Unofficial Wiki FAQ: cpwiki.sf.net

    My website: http://dwks.theprogrammingsite.com/
    Projects: codeform, xuni, atlantis, nort, etc.

  3. #3
    Kernel hacker
    Join Date
    Jul 2007
    Location
    Farncombe, Surrey, England
    Posts
    15,677
    DO:
    * Write overall comments on the functions in your code.
    * Comment on pieces of "special" code, e.g. some complicated calculation, principles of a condition, or such.
    * Use long variable and function names to avoid having to comment that "x is the number of foo-widgets" - call the variable "fooWidgetCount", and no one will ever wonder what it does [unless they don't know what a foo widget is of course].

    DON'T:
    * Put so many comments that you can't find the actual code.
    * Comment on things that are obvious anyone who understands the language
    Code:
    a++;  /* increment a */
    --
    Mats
    Compilers can produce warnings - make the compiler programmers happy: Use them!
    Please don't PM me for help - and no, I don't do help over instant messengers.

  4. #4
    C++まいる!Cをこわせ! Elysia's Avatar
    Join Date
    Oct 2007
    Posts
    22,630
    First and foremost - don't put comments how the code works (because programmers can read your code), instead put comments about what the code does. If you do, then readers will have a better understanding of how it all works and can more easily puzzle together what in the code does what.
    Feel free to comment complex code, and conditional statements with comments that typically expresses when the code in the if is executed. Again, it helps you understand the code.
    Don't put obvious comments everywhere, like increment i - we aren't dumb!
    Quote Originally Posted by Adak View Post
    io.h certainly IS included in some modern compilers. It is no longer part of the standard for C, but it is nevertheless, included in the very latest Pelles C versions.
    Quote Originally Posted by Salem View Post
    You mean it's included as a crutch to help ancient programmers limp along without them having to relearn too much.

    Outside of your DOS world, your header file is meaningless.

  5. #5
    Registered User
    Join Date
    Dec 2007
    Posts
    67
    cheers. then how would i properly describe this execution in the hash function?
    Code:
    h ^= ( h << 5 ) + ( h >> 2 ) + p[i];
    i know it has something to do with shifting but beyond that i have no clue

  6. #6
    Kernel hacker
    Join Date
    Jul 2007
    Location
    Farncombe, Surrey, England
    Posts
    15,677
    Describing that as a "hash function" is probably sufficient. It is actually "set h to h xor ((h * 32) + (h / 4) + p[i])" - which is going to mix the bits up quite well - and the art of coming up with a good hash method is one of those subjects that some computer scientists/mathematicians have written entire PhD thesis on.

    --
    Mats
    Compilers can produce warnings - make the compiler programmers happy: Use them!
    Please don't PM me for help - and no, I don't do help over instant messengers.

  7. #7
    Code Goddess Prelude's Avatar
    Join Date
    Sep 2001
    Posts
    9,796
    >then how would i properly describe this execution in the hash function?
    That looks like SAX. If it's a named algorithm, just put a single line comment in giving the name and possibly a potential resource for more details. You don't need to explain how the math works. Concerning hashes, if it's not a named algorithm, it's probably wrong.
    My best code is written with the delete key.

  8. #8
    Kernel hacker
    Join Date
    Jul 2007
    Location
    Farncombe, Surrey, England
    Posts
    15,677
    Quote Originally Posted by Prelude View Post
    >then how would i properly describe this execution in the hash function?
    That looks like SAX. If it's a named algorithm, just put a single line comment in giving the name and possibly a potential resource for more details. You don't need to explain how the math works. Concerning hashes, if it's not a named algorithm, it's probably wrong.
    Both of that makes a lot of sense - hashes aren't something you can just make up yourself [at least if you want it to spread nicely over the whole hastable, see my previous comment on "PhD thesis" etc], and the good ones are all documented somewhere or other - so assuming you got the hash mechanism from somewhere, just refer to that, e.g. "Using method XXX from YYY by Author Lastname" or "This hash algorithm comes from www.cprogramming.com/somepage".

    --
    Mats
    Compilers can produce warnings - make the compiler programmers happy: Use them!
    Please don't PM me for help - and no, I don't do help over instant messengers.

  9. #9
    Registered User
    Join Date
    Dec 2007
    Posts
    67
    yeah it is a SAX hash. thanks a lot guys

  10. #10
    C++まいる!Cをこわせ! Elysia's Avatar
    Join Date
    Oct 2007
    Posts
    22,630
    Hashes may be complex, but even if you explain like "first I do this and then I shift X bits and XOR with Y to get result Z" you're not helping much because I can read all that from the code.
    Quote Originally Posted by Adak View Post
    io.h certainly IS included in some modern compilers. It is no longer part of the standard for C, but it is nevertheless, included in the very latest Pelles C versions.
    Quote Originally Posted by Salem View Post
    You mean it's included as a crutch to help ancient programmers limp along without them having to relearn too much.

    Outside of your DOS world, your header file is meaningless.

  11. #11
    Code Goddess Prelude's Avatar
    Join Date
    Sep 2001
    Posts
    9,796
    >you're not helping much because I can read all that from the code.
    Yep. The way I explain commenting to my team is that any given piece of code causes you to ask one of three questions:

    1) "What is it doing?"
    2) "Why is it doing that?"
    3) "How is it doing that?"

    Code and comments work together to answer those questions.

    Question 1 is always answered with a comment[1].

    Question 2 is always answered with a comment. Code can't tell you why it's doing something.

    Question 3 is always answered with code. The very definition of code is to outline the steps for solving a problem.

    With that in mind, any comment that doesn't answer question 1 or 2 is a bad comment. Our code reviews take comments very seriously, and I often find myself following this line of conversation:

    Me: "What's this doing?"
    Coder: "It's doing <blah blah> for <blah blah> to <blah blah>."
    Me: "Why did you have to tell me that?"
    Coder: "Because it's badly commented?"
    Me: "You got it in one."

    [1] Transparent code also answers this question, but transparency is too subjective. So I just tell my team to treat question 1 as an "always comment". This saves the newbies from an experienced coder's ego, and it saves experienced coders from a newbie's bad judgement.
    My best code is written with the delete key.

  12. #12
    Fountain of knowledge.
    Join Date
    May 2006
    Posts
    794
    Personally I don't know if it matter much how you comment. If I am writing some code for myself I do tend to put a few comments in here and there but I find I hardly ever read them again, because obviously I know what my functions do, or should do
    Also I know if I have to hack a bit of code about a bit to get it working won't bother changing the comments!!

    Obviously if you are writing the code for someone else you have to follow there conventions whatever they maybe. I have certainty been told to comment like this on occasions
    Code:
     
    i++; // increment i
    Futhermore if I am looking at someone else code I don't bother too much with the comments either because that is usually when there is problem (bug) with the code so it obviously does not do that it is supposed to do anyway.

    At the end of the day the code does what it does, *not necessarily* what the comments say it does!!

    Anyway if you give your variables etc... half decent names it should be fairly self explanatory.

    Mind you, often when I am writing code I am not too sure what I am trying to do in the first place, I sort minor details like that out later

  13. #13
    C++まいる!Cをこわせ! Elysia's Avatar
    Join Date
    Oct 2007
    Posts
    22,630
    As always, esbo tends to pick some bad practices
    It doesn't matter if it's you or someone else who's going to read the code - always write comments.
    Again, don't write what the code does, that's rather useless, but what instead what the code is supposed to do.
    One day, if you left the project alone, or if someone else needs to read your code, then both of them will find themselves not knowing the code and have to familiarize themselves with it again. That's where comments come in handy.
    Keep your comments up-to-date. If something changes, update the comment. Comments that give false information is worse then no comments at all.
    Quote Originally Posted by Adak View Post
    io.h certainly IS included in some modern compilers. It is no longer part of the standard for C, but it is nevertheless, included in the very latest Pelles C versions.
    Quote Originally Posted by Salem View Post
    You mean it's included as a crutch to help ancient programmers limp along without them having to relearn too much.

    Outside of your DOS world, your header file is meaningless.

  14. #14
    Banned
    Join Date
    Nov 2007
    Posts
    678
    Hey dwks! Thanks for showing this example!
    I really liked this style of commenting!
    Code:
    /*------------------------*\
     | I Liked This Style! :) |
    \*------------------------*/

  15. #15
    Code Goddess Prelude's Avatar
    Join Date
    Sep 2001
    Posts
    9,796
    >I know what my functions do, or should do
    You have better memory than the majority of programmers then. If you churn out any reasonable amount of code on a regular basis, you'll find that you've forgotten what you were thinking when you wrote something. Sure, it's written in your style and you can figure it out (eventually), but comments would make the process much faster.

    It's also not uncommon to be asked to maintain code you wrote years ago, and at that point your code looks like it was written by someone else. I look at some of the code I posted on this forum a couple of years ago and I wonder if it was really me that wrote it.

    >Also I know if I have to hack a bit of code about a bit
    >to get it working won't bother changing the comments!!
    If the code and comments disagree, both are probably wrong.

    >Anyway if you give your variables etc... half decent
    >names it should be fairly self explanatory.
    That only goes half-way. See my questions and try to answer "why is it doing that?" with good identifier names. For example, you can write the most transparent bubble sort function on the planet, but I'm still going to ask why you're using bubble sort. That's where a comment is necessary.
    My best code is written with the delete key.

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

Similar Threads

  1. Replies: 1
    Last Post: 03-21-2006, 06:52 AM
  2. Updated sound engine code
    By VirtualAce in forum Game Programming
    Replies: 8
    Last Post: 11-18-2004, 11:38 AM
  3. Interface Question
    By smog890 in forum C Programming
    Replies: 11
    Last Post: 06-03-2002, 05:06 PM
  4. cygwin -> unix , my code not working properly ;(
    By CyC|OpS in forum C Programming
    Replies: 4
    Last Post: 05-18-2002, 04:08 AM
  5. Replies: 4
    Last Post: 01-15-2002, 11:04 PM

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