C++ Comments

I always try to write my comments in Doxygen style. You know, documenting every argument and return value for every method in every class. For example, the following could be part of a Vector class definition (and similar things for each file and datatype and variable):

Code:

---

  /**
  * Gets the length of the vector.
  * @return The length of the vector.
  */
  T computeLength();

---

However, I kind of get tired of the repetitive nature of this. Documenting functions whose meaning is completely clear without documentation and writing pretty much the same text for several fields or similar functions. It's just brain-numbing, writing such comments.

So, how do you document those header files? Do you document every single function, or do you skip the obvious? Can you give a few examples of how you would actually comment functions?


Thanks in advance

I only document library classes/functions like that when they will be used by other programmers and yeah then I do all. For non reuse code I dont do that. Since most of the time is spent in project specific which merely use libraries it doesnt feel so repetitive

I document every single function. If they're just getters/setters, copy & paste is faster -- then I just change a few words.

Thanks for the replies so far guys ;-).

Quote:

---

Originally Posted by cpjust

I document every single function. If they're just getters/setters, copy & paste is faster -- then I just change a few words.

---

Yes, I've tried to do it as well. But it gets so tiring...
I always end up stopping projects when I get to the boring parts, because it's too much work with too many challenges. And comment writing lacks any form of challenge.
Shrug.

Anyways, could you guys give a few examples of HOW you would comment functions? What format and what information would you write?

Quote:

---

Originally Posted by EVOEx

Anyways, could you guys give a few examples of HOW you would comment functions? What format and what information would you write?

---

I use something along the lines of the .NET/Gtk+/Qt documentation style...

Like so:

Code:

---

/**
 * Removes the specified item from the list if it exists.
 *
 * This function requires the value type to implement operator==().
 *
 * @param item the item to remove.
 *
 * @returns true if the item was removed, false otherwise.
 */

bool Remove(const T& item)
{
...
}

---

I also add @throws for the exceptions the method could throw if necessary.

Like KIBO, I tend to use Doxygen style comments for reusable components. Even then, I would only use such comments for the interface. Private member functions and helper functions defined in an anonymous or detail namespace do not normally get such detailed treatment from me (i.e., comments for them would usually be a note about the implementation, not the function's interface).

I comment like this:

Code:

---

/**
 * Put a description of what the function does here.
 *
 * @param var1 [IN] - Description of what this Input-only parameter is used for.
 * @param var2 [OUT] - Description of what this Output-only parameter is used for.
 * @param var3 [IN/OUT] - Description of what this Input/Output parameter is used for.
 *
 * @return - What does this function return.
 *
 * @throws SomeException - In what cases will this exception be thrown.
 */

---

I explicitly state whether the parameter is used for input only, output only (it's value is not used, but it is written to), or input/output (it's value is used and then it's modified). I usually also specify any default values, but that's probably just a bad habit since I think Doxygen does that for you in its HTML output.

Okay, thanks guys. I think I do pretty much what you do, cpjust, in a slightly different format. It's mind-numbing but I guess I'll keep doing it.
There's a good idea for IDE's though... Automatically add comments in before function declarations. Eg. if you add a function "setPosition" it will automatically add a comment using a template specific for functions in the format set*:

Code:

---

/**
 * Sets the [NAME_REST].
  ... More automatic fields ...
 * @return The [NAME_REST].
 */

---

That feature save a lot of time...