OGRE coding and style guidelines

[Owen]

Thats a C legacy.

Code: Select all

void func1();
void func2(void);
void func3(...);

In C: func1 is equivilent to func3, as in, pass all the parameters you want and theres no parameter checking. func2 accepts no parameters and will generate a compile error if you pass one. This is a legacy of the really early C compilers where function definitions couldn't have parameters in them.
In C++: func1 is equivilent to func2 - that is, empty parentheses indicate the function takes no parameters, since C++ decided to do away with compatibility with really old C.

[jacmoe]

Thats a C legacy.

Code: Select all

void func1();
void func2(void);
void func3(...);

In C: func1 is equivilent to func3, as in, pass all the parameters you want and theres no parameter checking. func2 accepts no parameters and will generate a compile error if you pass one. This is a legacy of the really early C compilers where function definitions couldn't have parameters in them.
In C++: func1 is equivilent to func2 - that is, empty parentheses indicate the function takes no parameters, since C++ decided to do away with compatibility with really old C.

No, it isn't.
This topic deals with Ogre coding and style guidelines, as preferred by the Ogre developers.

func2 is the explicit version of func1. In C++, () will become a void value.
And - with C++0x, we will have our func3 back: variable parameters.

[Owen]

Perhaps I should have phrased my post better :p

[wonderswan]

Just found this thread and the code style guide pdf and html. In general I agree with most of it, simply because it is readable and very much like how I do things myself.

However, while somewhat inconsequential, from a readability perspective I'd like to point out that indenting the cases of a switch increases code readability by emphasising code structure and logical cohesion, and that namespaces being the only S-structure to have its open brace on the same line as the declaration is inconsistent and contributes nothing to code readability (everything under a namespace should be indented to emphasise this anyway).

Removing this inconsistency would also have the additional benefit of reducing guideline rule complexity by subsuming braces placement to one rule:

All S-structures (any code construct that is delimited by braces "{ ... }") have their open and close bracers on their own lines. Examples:

Code: Select all

namespace Ogre
{
    ...
}

class Class
{
    ....
};

if (true)
{
    ....
}

[Assaf Raman]

From the first post:

...
http://jabberstudio.org/~temas/howto.pdf (pdf version, may be out of date)
...

Does anyone have that PDF and can post it?

[Crashy]

I'd like to add one note about asserts in header inlined functions.

On windows, an assertion displays a dialog box and it's possible to jump to the assertion line and debug, but there are two problems:
-Sometimes the call stack and the members informations are corrupted.
-When the assert is in an inline function, there is no way to see object's member values.

It's really painfull, as there is no way to simply break into the function when the assert condition is not verified, and the only real way to properly break is to modify the function, and in case of headers, it's sometimes a synonym of whole project recompilation.

Example:

Code: Select all

ID3D11ShaderResourceView *getTexture() 
		{ assert(mpShaderResourceView); return mpShaderResourceView; }

If I want to see why it's asserting, I must modify the function to something like

Code: Select all

ID3D11ShaderResourceView *getTexture() 
		{ 
			if(!mpShaderResourceView)
			{
				LogManager::getSingleton().logMessage("ID3D11ShaderResourceView::getTexture: mpShaderResourceView is NULL");
                                assert(0);
			}
			return mpShaderResourceView; 
		}

And set a breakpoint in the test's scope.
I know many people loves asserts, but from my point of view there are cases where it's more painfull than helpfull.

[FlorianGeorge]

You can also make asserts a bit better readable by adding something like

Code: Select all

assert(mpShaderResourceView && "ID3D11ShaderResourceView::getTexture: mpShaderResourceView is NULL")

that will, in case mpShaderResourceView is null, display everything inside the brackets. In this case it's trivial but sometimes it's not fully clear what special case an assertion was created to detect, and why.

[bstone]

If you don't like them - #undef assert in your global configuration header (it's always good to have one) for the project in question. I prefer crtdbg.h implementation (_ASSERT and _ASSERTE). Try adding <crtdbg.h> to your global header file, #undef'ing assert, and redefining it to _ASSERT. They seem to have been implemented differently as I never had an issue with them and I'm talking about working with ATL/WTL code base for years which is about 98% inline functions in template classes.

[jacmoe]

We can't really use Microsoft specific memory leak detection in Ogre related code as it's not cross platform and because Ogre has it's own memory leak detection scheme (IIRC).
So that assert macro should definitely be undefed. It's intrusive.

[bstone]

All correct. My suggestion was about a temporary fix that would let Crashy deal with what annoyed him during Windows debug sessions.

[jacmoe]

D'oh - I should've read more than just the last post.

[Roman]

In http://temas.obelisk.net/ogre/CR/docs/howto.html ...

Example 11. C++ Style Headers

Code: Select all

#inclue <cstring> // Acceptable
#include <string.h> // UNACCEPTABLE

Has anyone ever noted the erratum in 'include'?

[smsabbir480]

I appreciate.

[raffamaiden]

A preliminary version can be found here:
http://temas.obelisk.net/ogre/CR/docs/howto.html

Gives 404

[Kojack]

A preliminary version can be found here:
http://temas.obelisk.net/ogre/CR/docs/howto.html

Gives 404

Looks like the link has been broken for at least 2 years (way back machine says it was broken in 2014).
The last good version I could find is from 2011: https://web.archive.org/web/20111016044 ... howto.html

[paroj]

I think it was superceded by the CodingStandards which you can find inside the Docs folder: https://github.com/OGRECave/ogre/blob/m ... andards.md

[Kojack]

Good point.