Style guide

[1337]

I just wanted to have a look at the coding rules from yesterday:
http://www.orxonox.net/wiki/CodingRules

But this is definitly not the document we've seen. ("{" in while or if, the last part of the document..)

So: where is the actual one?

Edit: Found it: http://www.orxonox.net/wiki/c%2B%2B_styleguide
But how can one find it without the timeline?

[1337]

Oh, and what is about doxygen?

And I suggest that every function has a comment header with tags like author, what it does, bugs, etc. But this header should be consistent.

[1337]

Sorry, didn't realise that we are ALL allowed to make ANY changes in the wiki.

Link has been changed...

[patrick]

You are totally right. I forgot a few things to add to the guide. So please, if you find something or propose something, just add it to the guide and ask people for feedback here in the forum.

Good thinkging!

[greenman]

Added a link to the style rules in the tracnav menu.

If you want to we can also delete the link to the Coding Manifesto in order to prevent irritation.

[1337]

I've just come across a 'problem' with Doxygen: It is possible to write a comment for a function in the header file and in the code file.
Now, on the doxygen homepage there is a description of what will be taken in this case (Brief descrition from header, detailed one from the source).

Since I haven't programmed with doxygen at all, I ask the experienced ones: Where shall I place my comments with @param, etc.? Is it better to keep everything in the header files in order to make it easier for external programs? Or is in that case the readability of the source code restricted? Anyway, copying comments would not be my preferred solution.

[x3n]

But this is definitly not the document we've seen. ("{" in while or if, the last part of the document..)

Personally I prefer to put the "{" on a new line, but that's one of the less important points in the styleguide

[1337]

But this is definitly not the document we've seen. ("{" in while or if, the last part of the document..)

personally i prefer to put the "{" on a new line, but thats one of the less important points in the styleguide

Agreed. I'm so used to putting '{' on a new line...

[beni]

So change it accordingly. You guys wouldn't have gotten the rights to do that what you can do if we would not want you to do it .

I agree with the "{" I'm used to do it both ways, but I learned it like you guys in the olden days.

About the doxygen: I'd put everything at the beginning. Then nobody has to search for the stuff, but has it right at the top. IMO...

[1337]

About the style guide and the '{': I don't think that this is important enough to define a clear rule. I wouldn't mind, if we did that mixed ways.
However, the '{' in a function is quite important, since it structures the code.

And by the way: I really don't think if everyone changes the style guide according to one's preferences. Lets put such things in this thread in order to discuss it first.


Oh, @beni: what exactly do you mean by "put everything at the beginning" with Doxygen? The comments for the functions certainly should be above each function, not at the beginning of the file.
My question actually was wheter to put the Doxygen comments in the the header files or in the source files.

[beni]

Oh I thought you meant at the beginning of the function or inside the function. If I'm not mistaken one can put stuff for doxygen inside a function.

I think a short description in the header file and a detailed one in the source file is the best, as suggested on the doxygen site.

[1337]

I feared so.

For the rest, I'll keep it short since I have already written it all once (just clicked wrongly on a button on the page, schwups, everything was gone):
- deleted "main_reto", added a real branch "main_reto" and "main_reto_vs05", in which I keep my up-to-date files for now
- make... that's gonna cost me a lot of time to understand and to set up MinGW with gcc (the latter being the small problem).
- Everything edited to fit the style guide more or less.
- Every function now has a comment.


btw: sorry for the missing svn comment for the last commit. I had it all written nicely, but there was an error during the commit (version mismatch...). So I updated and then commited again, this time hitting OK very quickly... Curiously, nobody has commited anything today except me..

[1337]

I have a suggestion for the namespace part in the style guide:

Don't write "using namespace ..;" in header files because otherwise if someone included that header file, the "using namespace .." would automatically be included as well. That may lead to unwanted errors.

I'm not sure whether I'm telling crap, because if you don't write "using" in header files, you'll have to write e.g. Ogre:: many times... Although I don't think that is such a problem considering the side effects of "using".

[x3n]

yes, youre right. and the "Ogre::" thing is no problem, as we'll use Ogre mainly in base-classes.

oh, and dont forget the following style rule:

Names representing namespaces should be all lowercase.

so: Orxonox -> orxonox

[1337]

ok, the last part is crap for my work in the last few hours... But no problem to fix: find and replace through files...

But I agree: even though Ogre and OIS are upper case, lowercase makes more sense:
namespaces -> Classes -> variables and functions

Ha, already done

edit: added the '_s' postfix to clarify static class variables.