Names

• What: Some letter combinations are keywords.
• Who: C++ users, but especially C users.
• Why: The C standard is very braindamaged on how naming can and should be used. A lot of stupid things are allowed. Sometimes, it is legal to use reserved (system)identifiers for your own variable names. The program's behaviour is another thing entirely.

Do: Please do avoid the following

• <code>str...</code> is a reserved namespace! So are <code>is...</code>, <code>mem...</code>, <code>to...</code>, and <code>wcs...</code> . Never have any external variables start with any of these combinations. You will start linking to functions you never knew existed. (Actually, you might not, but this being a reserved namespace should make you careful enough.)
• Having a <code>struct x</code>, <code>int x</code> in parallel is legal. It is also a good recipe for a fortnight of impossible debugging. Be careful about this: the standards allows lots of stupid 'conflicts' here. Use a new name for a new thing.
• Anything starting with underscores. Sometimes this is allowed, but it is better not to rely on this.
• There is a list available with all illegal names in C. (Illegal according to ISO, ANSI or both). It is depressingly long.
• In C++, you may find yourself using <code>#include <iostream></code> and <code>#include <iostream.h></code>. The difference is that the .h variety includes and adds everything to the current namespace. The non-.h variety leaves everything in the std namespace (so you need to prefix with <code>std::</code> before using).

• What: Determine on what platform you are compiling
• Who: Porters
• Why: trivial

The first one is the preferred one.

#ifdef

• Beos: __BeOS
• MacOSX / Darwin: __APPLE__ __ppc__
• FreeBSD: __FreeBSD__ __i386__ See porting-versions.html
• Irix: __sgi __mips
• Linux: __linux__ __i386__ __sparc__ __alpha__ __powerpc__
• Solaris: __sun __sparc __i386
• Windows: _WIN32 WIN32

#endif

• (on gcc:) You can test for predefined names and paths with 'gcc -v filename.c'
• (on gcc:) Doing 'echo foo | gcc -dM -E -' lists the set of equivalent #define-s for compiler and library versions.

• What: Determine how and where functions are visible.
• Who: Everybody (especially C users).
• Why: It should be clear which functions are visible where, without looking at linking order or build order. A declaration serves a a sort of contract, where the builder of a function promises to deliver certain functionality. Users shouldn't have to peek at the implementation details to know what is going on. Implicitly declared functions will always return int, and are assumed to return a value, even if they are later on declared to do this differently. Often you will get a link warning/error, but not always.

• Write declarations for all functions, especially externally visible ones.

• What: How to choose variable and function names.
• Who: Everybody.
• Why: A uniform naming strategy helps when you are studying a new piece of code. It also frees you from the task of having to come up with yet another stupid name.

• Choose sensible, descriptive names. Even though the C standard specifies only the first 6 characters have to be used for linkage, this is not true for any modern compiler (notably: Gcc, Visual C++ and the Irix C compiler). Do not feel restricted in name-length (but don't overdo it, of course).
• A member variable from a class is prefixed with m_. Do not prefix other variables this way.
• We don't do extensions to indicate types and such. So don't make iInteger, CClass, bBoolean and so forth.

Externally visible names must comply to the following rules. It is a good idea to also make internal names comply:

• c/c++: Function names always start with lower caps.
• c++: Member names always start with a capital.
• c/c++: Words within a variable name are separated with underscores, and are all lower caps. This is more readable than the Java-style with caps for each new word.
• Function-local variables: Pick whatever you find convenient. Try to stick to lower caps, try to keep the names short. Local names may never clash with global names. If this happens, this is a mistake in the implementation of the local name. External names are designed be be easily avoidable.

• Member variable for counting flutzpahs: m_flutzpah_count
• Method for getting the flutzpah count: GetFlutzpahCount

• What: Use prefixes to mark functions and variables in external interfaces
• Who: Everybody.
• Why: Avoid name clashes, make interface usage clear, make dependencies on other modules and libraries explicit.

Do: At this moment, the following prefixes are in use:

• GEN: General stuff (c++)
• SM: SuMo (Solid Uses Moto), the physics engine (c++)
• KX: Ketsji, the game engine (c++)
• MT: MaTh, mathematics module (c++)
• RE: Render, static rendering (c)
• PR: Portable Runtime, a Netscape library (external code, c)
• PRB: PR-Blender, our own extensions to PR (c)
• SND: SouND, our (currently OpenAL) wrapper and extensions (c)
• RAS: RASterizer, our low level 3D polygon abstraction layer (c++)
• NET: NETworking. Currently our Terraplay CNI wrapper.
• BLI: Blender low-level LIbrary.
• BKE: Blender KErnel.
• BIF: Blender Interface Framework.
• BSE: Blender Space Editor.
• BDR: Blender DRawing.
• DNA: struct DNA, the types definitions of serializable data, and the construction of DNA.o, which encodes this data.
• AVI: conversion of AVI format files.
• IMB: IMage Buffer, all kind of operations on images.

Not everything is a module yet... But we should work on getting there.

Function

<ccode>pickFlowers()</ccode>in the external interface of the GEN module should be called

<ccode>GEN_pickFlowers()</ccode>

Back to Coding Style