[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Coding Standards
Peter Burns wrote:
>Are there any coding standards for this project?
>By this I mean standards for naming variables, classes, etc,
>coding style, the way code should be indented, where to stick braces
Well, yes, there exists a minimalistic draft of such standards, but it's
not on the website yet (good that you remind me of it). I attached it below.
AAAAA - American Association Against Acronym Abuse
Title: PenguinPlay Coding Standard Draft
OK this is a draft of a minimal coding standard designed for PPlay. This is
only a draft, or more accurately, a discussion doco, mostly I am stating my own
opinion so you should probably tell me why I am wrong (or just tell me to shut
up and tow the line). This doco does not even neccesarily reflect the
currently used coding practices. I have also left some issues open.
I'm not sure if we ever got around to figuring out prefixes to use for
what. So I will just list the ones already in use, and if you need
to invent a new one, go ahead.
pp - General stuff.
ppg - Graphics.
So the only real rule is to not cause a collison and start with pp.
Also if you have one of those must-be-public-even-though-we-want-to-hide-it
things, then prepend a _, if is a macro then "prefix" becomes "PREFIX_"
(or _prefix becomes _PREFIX_). You know, common sense.
If I have my way then _everything_ which is public, whether of global
scope or not, should be in CapsForTheStartOfEachWordIncludingTheFirst.
What is private is private (although I prefer simples_with_underscores).
For some reason, C++ programmers around the world seem to do the same,
except class members are capForStartOfAllButTheFirstWord.
I think this is insane because
- It is strange.
- If it is only one word long, then
- It is strange.
But if everyone else wants to do it this way, then I will go along
As far as the user is concerned, _every_ PPlay header file is to be gotten
The actualy CVS tree has an include/ directory in both the root and
each project branch, that is only there for conveninece, "make install"
will destroy all those distinctions. Any header directly in a
include/ directory should be moved to include/PenguinPlay/.
I have simply named each header after the most important class defined in it.
So ppgGC is in ppgGC.h. I think this is the simplest thing, but most people
seem to used small letters, so ppgGC would be gc.h. I think I am more
logical. So should I change or should everyone else?
Multiple Inclusion Protecton
When protecting header files using an #ifndef block I am using the macro name
"_FileNameWithoutTheExtension_h". Everyone else prefers something involving
ALL_CAPS_AND_UNDERSOCRES. My system is logical because it just preserves the
filename wheras the other is logical because macros should be in all
capps. Even the all caps people are using different systems. I suggest maybe
"_PF_BASNAME_H" for the file "pfBaseName.h", where pf is the prefix.
Holy war time. I say, do what you feel like but be invisible when you change
someone elses file. I've been using two space, but even I don't even know if
that is a good idea.
One thing though. I don't like tabs, they only cause trouble for people with
different tab stops on thier editors, no matter how hard you try to get it
right. Even if you don't agree with this, what I find intolarable is
indentation done with a mixture of spaces and tabs, when you see code like that
it's unreadable till you guess the tab spacing. I seem to remember Emacs doing
I don't think we should really make rules about this. Only _please_
put a description of what a file is for in the title block or somewhere.
I really hate having to hope that I am reading the right file.
Also I have written much of pg2d with the assumption that we will be
autogenerating documentation using a tool called Perceps. Once I had the
actuall doc generation stuff in the build system, but not anymore (can't
remember what happened, CVS wars probably). Anyway, Perceps is cool,
check it out here.