Thread: C++ Comments

  1. #1
    Registered User
    Join Date
    Oct 2008
    Posts
    1,262

    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

  2. #2
    Registered User
    Join Date
    Jan 2007
    Posts
    330
    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

  3. #3
    and the hat of sweating
    Join Date
    Aug 2007
    Location
    Toronto, ON
    Posts
    3,545
    I document every single function. If they're just getters/setters, copy & paste is faster -- then I just change a few words.
    "I am probably the laziest programmer on the planet, a fact with which anyone who has ever seen my code will agree." - esbo, 11/15/2008

    "the internet is a scary place to be thats why i dont use it much." - billet, 03/17/2010

  4. #4
    Registered User
    Join Date
    Oct 2008
    Posts
    1,262
    Thanks for the replies so far guys ;-).

    Quote Originally Posted by cpjust View Post
    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?

  5. #5
    Registered User
    Join Date
    Aug 2005
    Posts
    96
    Quote Originally Posted by EVOEx View Post
    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.

  6. #6
    C++ Witch laserlight's Avatar
    Join Date
    Oct 2003
    Location
    Singapore
    Posts
    28,413
    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).
    Quote Originally Posted by Bjarne Stroustrup (2000-10-14)
    I get maybe two dozen requests for help with some sort of programming or design problem every day. Most have more sense than to send me hundreds of lines of code. If they do, I ask them to find the smallest example that exhibits the problem and send me that. Mostly, they then find the error themselves. "Finding the smallest program that demonstrates the error" is a powerful debugging tool.
    Look up a C++ Reference and learn How To Ask Questions The Smart Way

  7. #7
    and the hat of sweating
    Join Date
    Aug 2007
    Location
    Toronto, ON
    Posts
    3,545
    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.
    "I am probably the laziest programmer on the planet, a fact with which anyone who has ever seen my code will agree." - esbo, 11/15/2008

    "the internet is a scary place to be thats why i dont use it much." - billet, 03/17/2010

  8. #8
    Registered User
    Join Date
    Oct 2008
    Posts
    1,262
    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...

Popular pages Recent additions subscribe to a feed

Similar Threads

  1. [C] remove comments
    By Tool in forum C Programming
    Replies: 50
    Last Post: 11-29-2009, 04:57 AM
  2. removing comments of type '//' and '/*'
    By rohit83.ken in forum C++ Programming
    Replies: 3
    Last Post: 10-20-2007, 02:24 AM
  3. String parsing(parsing comments out of HTML file)
    By slcjoey in forum C# Programming
    Replies: 0
    Last Post: 07-29-2006, 08:28 PM
  4. The Art of Writing Comments :: Software Engineering
    By kuphryn in forum C++ Programming
    Replies: 15
    Last Post: 11-23-2002, 05:18 PM
  5. ignoring comments
    By wjday in forum C Programming
    Replies: 11
    Last Post: 04-24-2002, 11:16 AM