Thread: how to properly comment on c code

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.

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

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!

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

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

Originally Posted by Prelude

>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

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.

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

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.

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