Commenting style

[Lwmte]

This one also needs to be defined in some way. TeslaRus have this "asterisks-and-slashes" style (don't remember proper name of this style), while I generally comment anything with twin slashes. Cochrane also tried to introduce Doxygen-styled comments.

I think that eventually we need to make all comments either Doxygen-compatible, or single-styled. While I wanted to "doxygenify" everything at some point, now I see no real benefit from it - for ex., Bullet uses Doxygen for automatic manual generation, but this manual is 90% useless, as in most cases it ends up with "Definition X at line X", so I have to dig into code or forums anyway.

What do you think?

[stohrendorf]

Even more important than a comment style is a naming style; comments are most of the time only necessary if identifiers aren't named correctly. E.g., renaming all those bb_min and bb_max to boundingBoxMinCoords and boundingBoxMaxCoords would make all those // Hey, this is a bounding box coordinate comments obsolete, and it would eventually lead to a new struct BoundingBox containing the diagonal edges. And if comments are necessary, they should only describe interfaces (classes, functions) in a Doxygen-like style. (Or the famous r: sometimes it's just an r without any comment, sometimes it's secretly stored inside the W component of a vector. Or dist, maybe even distance: distance of what? This passport mesh to the next toilet?)

[cochrane]

I agree with both of you. Names of variables should be long enough to need no comments. If this isn't possible because the variable is used in a clever way, the cleverness should be removed. Interfaces (functions, classes, methods) should be documented. How much is a matter of taste, but at least the general idea of what it does. Comments within functions are generally a sign of functions that are too long. An overly long function with comments is better than one without, but it's a sign that two functions might be better.

Oh, and we need more but shorter files. Finding anything in them takes forever.

[stohrendorf]

Because I have some experience with huge modular projects, I'd suggest not only more files, but also grouping them into logical namespaces (physics, gui, rendering, level loading, lua interface, etc etc) as well as organizing them into subfolders correlating to that namespaces (e.g., a file containing only the namespace hierarchy rendering/buffer/vbo would live in that exact folder).

[ablepharus]

I am in favour of stohrendorfs proposal. I am alaso in favour of using doxygen commands.

[Lwmte]

I have found very neat document which contains some very useful directions (although not every direction there is right IMO), here is it.

Particularly, the chapter regarding comments:

You can use either the // or the /* */ syntax; however, // is much more common. Be consistent with how you comment and what style you use where.

I agree on this. Any other c++ I read before also says in favor of // styled comments. So I'd recommend everyone to use // styled comments only.

Regarding doxygen... It proved useless from my experience, so unfortunately I object against it. Maybe we'll return to this idea when code will be not so messed up, but at current state, I think introducing doxygen-styled comments will complicate things even more. Let code speak for itself for now.

[Lwmte]

Naming conventions: I'm perfectly fine with what Steffen is doing! :+1:

I should eventually move all these recommendations to #180...

[Gh0stBlade]

Personally, I want all the code clearly commented and explained. I try to comment everything where I can and have commented everything I've written so far. Just makes it easier to see if something is being mis-interpreted or not.