Examples of how to write beautiful comments in C ++

Question

maybe this is a stupid question, but is there a way to write a good (short) format to write comments for a C ++ function, headers, variables? any visual examples?

Answer 1

What do you mean by looking at me? I do it like this.

int c;//! loop Counter /** * compares (XOR) two Types * return boolean result */ bool compare(Type l, Type r); 

Its format is oxygen. Common formats exist for documenting codes in comments. Doxygen is one and the other is natural. there is even more. This is your taste. You might 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 similar to similer.

 /** 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 to it.

Answer 2

I prefer to use this style:

 /** * Class name * Description */ class MyClass{ } 

Answer 3

Some would suggest that the most beautiful comments are those that fit the entire program. I prefer to use slashes:

 // -- short concise comments in single lines like this // ----------------------------------------- // // Sectional Dividers Like This // // ----------------------------------------- 

However, this does not help if you are hoping to create documentation from your comments.

Answer 4

The best way is to make it so that some automated tool can extract them and create stitched documentation. Look at doxygen

Answer 5

I use the following style:

for the 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. */ 

Answer 6

Take a look at http://www.doxygen.nl/ . This is essentially a take-off in the JavaDoc format, where the format is interpreted to a certain extent for the help file.

I believe in self-documenting code, but a few well-understood comments may help.