OGRE coding and style guidelines

Discussion area about developing or extending OGRE, adding plugins for it or building applications on it. No newbie questions please, use the Help forum for that.
Owen
Google Summer of Code Student
Google Summer of Code Student
Posts: 91
Joined: Mon May 01, 2006 11:36 am
x 21

Re: OGRE coding and style guidelines

Post by 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.
User avatar
jacmoe
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 20570
Joined: Thu Jan 22, 2004 10:13 am
Location: Denmark
x 179
Contact:

Re: OGRE coding and style guidelines

Post by jacmoe »

Owen wrote: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.
:wink:
/* Less noise. More signal. */
Ogitor Scenebuilder - powered by Ogre, presented by Qt, fueled by Passion.
OgreAddons - the Ogre code suppository.
Owen
Google Summer of Code Student
Google Summer of Code Student
Posts: 91
Joined: Mon May 01, 2006 11:36 am
x 21

Re: OGRE coding and style guidelines

Post by Owen »

Perhaps I should have phrased my post better :p
User avatar
wonderswan
Halfling
Posts: 40
Joined: Fri Jul 11, 2008 8:56 pm

Re: OGRE coding and style guidelines

Post by 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)
{
    ....
}
User avatar
Assaf Raman
OGRE Team Member
OGRE Team Member
Posts: 3092
Joined: Tue Apr 11, 2006 3:58 pm
Location: TLV, Israel
x 76

Re: OGRE coding and style guidelines

Post by Assaf Raman »

From the first post:
:wumpus: wrote: ...
http://jabberstudio.org/~temas/howto.pdf (pdf version, may be out of date)
...
Does anyone have that PDF and can post it?
Watch out for my OGRE related tweets here.
Crashy
Google Summer of Code Student
Google Summer of Code Student
Posts: 1005
Joined: Wed Jan 08, 2003 9:15 pm
Location: Lyon, France
x 49
Contact:

Re: OGRE coding and style guidelines

Post by 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.
Follow la Moustache on Twitter or on Facebook
Image
FlorianGeorge
Halfling
Posts: 86
Joined: Tue Sep 01, 2009 7:15 pm
Location: Cologne, Germany
x 4

Re: OGRE coding and style guidelines

Post by 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
OGRE Expert User
OGRE Expert User
Posts: 1920
Joined: Sun Feb 19, 2012 9:24 pm
Location: Russia
x 201

Re: OGRE coding and style guidelines

Post by 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.
User avatar
jacmoe
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 20570
Joined: Thu Jan 22, 2004 10:13 am
Location: Denmark
x 179
Contact:

Re: OGRE coding and style guidelines

Post by 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.
/* Less noise. More signal. */
Ogitor Scenebuilder - powered by Ogre, presented by Qt, fueled by Passion.
OgreAddons - the Ogre code suppository.
bstone
OGRE Expert User
OGRE Expert User
Posts: 1920
Joined: Sun Feb 19, 2012 9:24 pm
Location: Russia
x 201

Re: OGRE coding and style guidelines

Post by bstone »

All correct. My suggestion was about a temporary fix that would let Crashy deal with what annoyed him during Windows debug sessions.
User avatar
jacmoe
OGRE Retired Moderator
OGRE Retired Moderator
Posts: 20570
Joined: Thu Jan 22, 2004 10:13 am
Location: Denmark
x 179
Contact:

Re: OGRE coding and style guidelines

Post by jacmoe »

D'oh - I should've read more than just the last post. :)
/* Less noise. More signal. */
Ogitor Scenebuilder - powered by Ogre, presented by Qt, fueled by Passion.
OgreAddons - the Ogre code suppository.
User avatar
Roman
Halfling
Posts: 92
Joined: Sun Nov 02, 2008 3:49 pm
Location: Germany

Re: OGRE coding and style guidelines

Post by 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
Gnoblar
Posts: 1
Joined: Sun Jul 20, 2014 2:59 pm

Re: OGRE coding and style guidelines

Post by smsabbir480 »

I appreciate.
raffamaiden
Gnoblar
Posts: 16
Joined: Wed Jul 29, 2009 12:30 pm
x 2

Re: OGRE coding and style guidelines

Post by raffamaiden »

:wumpus: wrote: A preliminary version can be found here:
http://temas.obelisk.net/ogre/CR/docs/howto.html
Gives 404
User avatar
Kojack
OGRE Moderator
OGRE Moderator
Posts: 7157
Joined: Sun Jan 25, 2004 7:35 am
Location: Brisbane, Australia
x 534

Re: OGRE coding and style guidelines

Post by Kojack »

raffamaiden wrote:
:wumpus: wrote: 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
OGRE Team Member
OGRE Team Member
Posts: 1994
Joined: Sun Mar 30, 2014 2:51 pm
x 1074
Contact:

Re: OGRE coding and style guidelines

Post by 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
User avatar
Kojack
OGRE Moderator
OGRE Moderator
Posts: 7157
Joined: Sun Jan 25, 2004 7:35 am
Location: Brisbane, Australia
x 534

Re: OGRE coding and style guidelines

Post by Kojack »

Good point. :)
Post Reply