Comments Style

[Maki]

Ind:

As brought up by Error404 and GodLesZ commenting is a very welcome habit which helps not only other developers to understand your code faster but to users trying to modify the source in some way.

I've given it a try on the r55 and would like to know your opinion on it, hows done, layout (got a better idea for a pattern? mines not good), etc. Let me know what you think.

Thank you for your time.

GodLesZ:

What about a whole doc on the source? this would help a lot new guys, like SRC funcs and whatnot.

Indeed, but this will be a lot of work and a over-time milestone.

We should try to document any point of code if we visit him and have some time.

This way i document old projects of mine which arent documented well.

Every time i visit the code to look for something or extend it, i add documentation to every spot i see. This dosnt take too much time @ once and documents the code over the time.

If we documented the most of the code we should setup a DoxyGen or another script to create a html or pdf document.

I know, double post, but its a totally new question.

We should decide a comment-style.

I like to use the XML-style, covered from my C# coding:

/// <summary>

/// Some description

/// </summary>

/// <param name="id">Session id</param>

/// <return>1 on any error</return>

int clif_some_function(int id) {

The other often used style is javadoc, commonly used in java, php ect.

(Note: Style may varry from user to user)

/**

* Some description

*

* @param id Session id

*

* @return int 1 on any error

*/

int clif_some_function(int id) {

It is most often a user question, but i hate it to see 5 or more comment styles in the eAthena code even in one file..

So i think someone has to clean it up and standardize them.

Once we had commented all in a regular same way, we may use tools to generate a whole server documentation (doxygen i.e.), like mentioned in the post above.

I will try to test some comment add-ins for Visual Studio to refactor comments. Also some simple scripts for parsing existing comments and standardize them wont be that hard.

[CalciumKid]

I personally like the XML comment style.

[Panallox]

The XML style isn't fully supported by C++ clients though. I know that javadocs; are supported, usually in either the format:

/**
* some line of description here outlining the process.
* @param something a description of something
* @return bool whether or not it is true!
*/

Or the same but:

/**
* some line of description here outlining the process.
* param something a description of something
* return bool whether or not it is true!
*/

I think having XML all over the place might look a little crowded? Just a thought

[Ind]

I personally agree with Epoque, I think it'd crowd the comments unnecessarily (XML). I'd rather go with javadoc

[Z3R0]

Using block comments on single lines underneath make it look overly complex...

I would suggest the full block @ the top (what it does)

then a mini block above each line of code

/*
* This is my super script from source and stuff kk?
*/
if (sd->rawr) {

 /* checks to see if he's online */
if (a ==  { }
}
/* end */

[Brian]

I'm fine with either block comment style. Doxygen can probably parse both =]

@Z3R0: but not comments for every single line, right?

Only for really complex lines that, at a glance, it's not immediately obvious what the code is doing.

[GodLesZ]

I'd like to suggest the style of my company I'm working on.

We use it for PHP, Python, Perl, C, C++ and even Assembler.

/**
* Description here,
* Even multilined.
* - 1 line space before params or return statements
* - 1 line space between params and return statements
*
* @param<TAB><name of param><TAB><Parameter description>
*
* @return<TAB><type of return><TAB><Return description>
*/

This is our style of comments and is used above every function/method/prodcedure and is supported natively from doxygen i.e.

I would love to see somedays every comment in that way <3

Also, if a comment takes 2 or more lines, we use multiline comment blocks. If not, single line comments of course.

Suggestions?

[pan]

Imo it would be better to use doxygen-styled comments, the doxygen itself generates an online documentation that's very good to search for functions. http://www.stack.nl/~dimitri/doxygen/

But after all it's all up to the devs to choose whether to use it or not...

[Brian]

Yes we plan to use doxygen.

Here's the link to the old eAthena Doxygen: http://eathena.sf.net/doxygen/

[Jonne]

I'd like to suggest the style of my company I'm working on.

We use it for PHP, Python, Perl, C, C++ and even Assembler.

/**
* Description here,
* Even multilined.
* - 1 line space before params or return statements
* - 1 line space between params and return statements
*
* @param<TAB><name of param><TAB><Parameter description>
*
* @return<TAB><type of return><TAB><Return description>
*/

This is our style of comments and is used above every function/method/prodcedure and is supported natively from doxygen i.e.

I would love to see somedays every comment in that way <3

Also, if a comment takes 2 or more lines, we use multiline comment blocks. If not, single line comments of course.

Suggestions?

Totally supporting that one. Nice and clean.

Question to the Style of GodLesZ:

When the i.e. the return value is returning error code like: 0 - no error, 1 - error and so on. How to you write that into description.

Like:

* @return<TAB>int<TAB>error code for calling function
* 0 - no error
* 1 - error

or else?

Edited December 30, 2011 by Jonne