Yerushalem Codeing Standards

Intro

Many people will code Yerushalem. Good communication is essential. On a large project such as this, it is not enough that you understand your code, everyone must be able to. Also, at some point you will move on in your life and will not be here to answer questions. So please be clear and use a lot of comments.

Structure

• Keep lines under 78 characters wide.
• Avoid using any editor that isn't Vim compatible.
• Indent.

Naming conventions

We will borrow from Crystal Space

• Class names: yeruSomeSelfDocumentingClassName
• Methods and functions: ThisIsAFunction()
• SCF interfaces: iThisIsAnSCFInterface
• Comments: Use Doxygen Style-- /** ... */ or ///

Documentation and comments

As I said above, I'm a real fan of comments. Use this procedure to ensure good commenting. The amount of commenting I'm asking for may seem insane, but I believe it will save a lot of time, and prevent many computers from being thrown out of windows.

Header Files

1. At the top of each header file write an overview stateing what the class does and how it does it and anything else that may be useful. If there are multiple classes in the file, do this for each class at it's definition, and also give one line summeries of each class at the top of the file.
2. Give further details for each method within the class. If the methods are repetitive in nature, you may simply give an html hyperlink to another function that does the same basic thing. But be sure to point out anything that is unique.
3. Document all varibles in the same way.

Source Files

1. Before each method restate what it does and how it does it.
2. For each method, write short simple english sentences stating each step the function will perform.
3. *Then* put a line of source after each sentance above.

Optimisation vs. Clarity

This is a game, and as such it is the most demanding piece of software computers commonly run. Yerushalem will be particularly demmanding. Therefore the code must be tight and fast.

That said, tight and fast code is hard for humans to understand. So, until the bulk of the source is written, don't worry about optimising your code if it means making it obfuscated.

Keep in mind the computer you are currently using will be obsolete by the time Yerushalem is released. Plan on 2.5-3+GHz processors with 1Gig of ram, and 200 Gigs of harddrive space and perhaps 128Mb+ 3D video card ram, being a somewhat low-end gaming system. This game will probably have to be released on double sided DVD.

That said, leave the crap code to M$. Faster, bigger computers are not to make your job as a programmer easier, but rather to make games more detailed, complex and fast.