Style guide

Get help with programming issues.

Moderator: PPS-Leaders

User avatar
1337
Baron Vladimir Harkonnen
Posts: 521
Joined: Wed Oct 10, 2007 7:59 am

Style guide

Post by 1337 » Thu Nov 01, 2007 8:46 am

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?

User avatar
1337
Baron Vladimir Harkonnen
Posts: 521
Joined: Wed Oct 10, 2007 7:59 am

Post by 1337 » Thu Nov 01, 2007 8:51 am

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.

User avatar
1337
Baron Vladimir Harkonnen
Posts: 521
Joined: Wed Oct 10, 2007 7:59 am

Post by 1337 » Thu Nov 01, 2007 12:25 pm

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

Link has been changed...

User avatar
patrick
Baron Vladimir Harkonnen
Posts: 350
Joined: Mon Oct 02, 2006 6:03 pm
Location: Bern

Post by patrick » Thu Nov 01, 2007 1:03 pm

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!

User avatar
greenman
Baron Vladimir Harkonnen
Posts: 360
Joined: Wed Oct 03, 2007 2:53 pm
Contact:

Post by greenman » Thu Nov 01, 2007 3:37 pm

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.

User avatar
1337
Baron Vladimir Harkonnen
Posts: 521
Joined: Wed Oct 10, 2007 7:59 am

Post by 1337 » Thu Nov 01, 2007 4:40 pm

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.

User avatar
x3n
Baron Vladimir Harkonnen
Posts: 810
Joined: Mon Oct 30, 2006 5:40 pm
Contact:

Re: Style guide

Post by x3n » Thu Nov 01, 2007 4:48 pm

1337 wrote: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 ;)

User avatar
1337
Baron Vladimir Harkonnen
Posts: 521
Joined: Wed Oct 10, 2007 7:59 am

Re: Style guide

Post by 1337 » Thu Nov 01, 2007 5:52 pm

x3n wrote:
1337 wrote: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...

User avatar
beni
Baron Vladimir Harkonnen
Posts: 949
Joined: Tue Oct 03, 2006 9:15 am
Location: Zurich
Contact:

Post by beni » Thu Nov 01, 2007 6:03 pm

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...
"I'm Commander Shepard and this is my favorite forum on the internet."

User avatar
1337
Baron Vladimir Harkonnen
Posts: 521
Joined: Wed Oct 10, 2007 7:59 am

Post by 1337 » Sat Nov 03, 2007 4:15 pm

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.

User avatar
beni
Baron Vladimir Harkonnen
Posts: 949
Joined: Tue Oct 03, 2006 9:15 am
Location: Zurich
Contact:

Post by beni » Sat Nov 03, 2007 7:40 pm

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.
"I'm Commander Shepard and this is my favorite forum on the internet."

User avatar
1337
Baron Vladimir Harkonnen
Posts: 521
Joined: Wed Oct 10, 2007 7:59 am

Post by 1337 » Sat Nov 03, 2007 10:25 pm

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..

User avatar
1337
Baron Vladimir Harkonnen
Posts: 521
Joined: Wed Oct 10, 2007 7:59 am

Post by 1337 » Sun Nov 04, 2007 4:10 pm

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".

User avatar
x3n
Baron Vladimir Harkonnen
Posts: 810
Joined: Mon Oct 30, 2006 5:40 pm
Contact:

Post by x3n » Sun Nov 04, 2007 4:53 pm

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 ;)

User avatar
1337
Baron Vladimir Harkonnen
Posts: 521
Joined: Wed Oct 10, 2007 7:59 am

Post by 1337 » Sun Nov 04, 2007 8:41 pm

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.

Post Reply

Who is online

Users browsing this forum: No registered users and 1 guest