examples of how to write beautiful c++ comments [closed]

It's difficult to tell what is being asked here. This question is ambiguous, vague, incomplete, overly broad, or rhetorical and cannot be reasonably answered in its current form. For help clarifying this question so that it can be reopened, visit the help center. 开发者_如何学C Closed 11 years ago.

maybe is stupid question but is there any way to write good looking (short ) format to write comments for c++ function,headers,variable ? any visual examples?

---

What do you mean by good looking here ? I do it like this ..

int c;//! loop Counter

/**
 * compares (XOR) two Types
 * return boolean result
 */
bool compare(Type l, Type r);

Its doxygen format. there are populer formats for documenting codes in Comment. Doxygen is one and another one is naturaldocs. there are even more. Its your flavour. You may even like the naturaldocs format.

/*
   Function: Compare
   Compares two Types
   Parameters:
      l - lhs
      r - rhs.
   Returns:
      boolean result

*/
bool compare(Type l, Type r);

The DOC++ format is also similer like.

/** Comparison
    Compare two Types

    @param l Type lhs
    @param r Type rhs
    @return boolean result
*/
bool compare(Type l, Type r);

Just use only one format and stick with it.

---

I prefer using this style:

/**
 * Class name
 * Description
 */

class MyClass{

}

---

Some would suggest that the most beautiful comments are those which are consistent throughout a program. I prefer to use forward slashes:

// -- short concise comments in single lines like this

// -----------------------------------------
//
//    Sectional Dividers Like This
//
// -----------------------------------------

That said, these won't help if you are hoping to generate documentation from your comments.

---

I use following style:

for method:

/**
 * Method description.
 * @param param1 param1 description 
 * @param param2 param2 description
 * @return return description
 * @since date since method is created
 * @author who have made this method.
 */

for variables:

/** variables description **/

for class:

/**
 * Class description.
 * @since date since class is created
 * @author who have made this class.
 */

---

The best way is to do it in such a way that some automated tool can extract them and create cross linked documentation. Have a look at doxygen

---

Take a look at http://www.doxygen.nl/. Basically, a take-off on the JavaDoc format, where the format is interpreted, to a certain degree, for a help file.

I'm a believer in self-documenting code, but a few well-versed comments can help a lot.