Re: Coding conventions.

[s369625@student.uq.edu.au]

>
>> What convention do we have for these macros? I used __PENGUINPLAY_H__ 
>> up to now. Perhaps we should write some "PenguinPlay coding standards"
>> doc ;)

Attached is a little try.

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.

Symbol Naming

Prefixes

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.

CaPItaLizatION

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

  Header Files

  Location

  As far as the user is concerned, _every_ PPlay header file is to be gotten by: #include 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/.

  Naming

  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.

  Indentation

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

  Comments

  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 .