www.pudn.com > 2005010815393829175.zip > conventions.rtf
{\rtf1\ansi\ansicpg1252\uc1\deff0\stshfdbch0\stshfloch0\stshfhich0\stshfbi0\deflang1033\deflangfe1033{\fonttbl{\f0\froman\fcharset0\fprq2{\*\panose 02020603050405020304}Times New Roman;}{\f1\fswiss\fcharset0\fprq2{\*\panose 020b0604020202020204}Arial;}
{\f36\fswiss\fcharset0\fprq2{\*\panose 020b0a04020102020204}Arial Black;}{\f37\fmodern\fcharset0\fprq1{\*\panose 020b0609040504020204}Lucida Console;}{\f38\froman\fcharset238\fprq2 Times New Roman CE;}{\f39\froman\fcharset204\fprq2 Times New Roman Cyr;}
{\f41\froman\fcharset161\fprq2 Times New Roman Greek;}{\f42\froman\fcharset162\fprq2 Times New Roman Tur;}{\f43\froman\fcharset177\fprq2 Times New Roman (Hebrew);}{\f44\froman\fcharset178\fprq2 Times New Roman (Arabic);}
{\f45\froman\fcharset186\fprq2 Times New Roman Baltic;}{\f46\froman\fcharset163\fprq2 Times New Roman (Vietnamese);}{\f48\fswiss\fcharset238\fprq2 Arial CE;}{\f49\fswiss\fcharset204\fprq2 Arial Cyr;}{\f51\fswiss\fcharset161\fprq2 Arial Greek;}
{\f52\fswiss\fcharset162\fprq2 Arial Tur;}{\f53\fswiss\fcharset177\fprq2 Arial (Hebrew);}{\f54\fswiss\fcharset178\fprq2 Arial (Arabic);}{\f55\fswiss\fcharset186\fprq2 Arial Baltic;}{\f56\fswiss\fcharset163\fprq2 Arial (Vietnamese);}
{\f398\fswiss\fcharset238\fprq2 Arial Black CE;}{\f399\fswiss\fcharset204\fprq2 Arial Black Cyr;}{\f401\fswiss\fcharset161\fprq2 Arial Black Greek;}{\f402\fswiss\fcharset162\fprq2 Arial Black Tur;}{\f405\fswiss\fcharset186\fprq2 Arial Black Baltic;}
{\f408\fmodern\fcharset238\fprq1 Lucida Console CE;}{\f409\fmodern\fcharset204\fprq1 Lucida Console Cyr;}{\f411\fmodern\fcharset161\fprq1 Lucida Console Greek;}{\f412\fmodern\fcharset162\fprq1 Lucida Console Tur;}}{\colortbl;\red0\green0\blue0;
\red0\green0\blue255;\red0\green255\blue255;\red0\green255\blue0;\red255\green0\blue255;\red255\green0\blue0;\red255\green255\blue0;\red255\green255\blue255;\red0\green0\blue128;\red0\green128\blue128;\red0\green128\blue0;\red128\green0\blue128;
\red128\green0\blue0;\red128\green128\blue0;\red128\green128\blue128;\red192\green192\blue192;}{\stylesheet{\ql \li0\ri0\widctlpar\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0 \fs24\lang1033\langfe1033\cgrid\langnp1033\langfenp1033 \snext0 Normal;}
{\*\cs10 \additive \ssemihidden Default Paragraph Font;}{\*
\ts11\tsrowd\trftsWidthB3\trpaddl108\trpaddr108\trpaddfl3\trpaddft3\trpaddfb3\trpaddfr3\trcbpat1\trcfpat1\tscellwidthfts0\tsvertalt\tsbrdrt\tsbrdrl\tsbrdrb\tsbrdrr\tsbrdrdgl\tsbrdrdgr\tsbrdrh\tsbrdrv
\ql \li0\ri0\widctlpar\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0 \fs20\lang1024\langfe1024\cgrid\langnp1024\langfenp1024 \snext11 \ssemihidden Normal Table;}{\s15\ql \li0\ri0\widctlpar
\tqc\tx4320\tqr\tx8640\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0 \fs24\lang1033\langfe1033\cgrid\langnp1033\langfenp1033 \sbasedon0 \snext15 \styrsid1516251 header;}{\s16\ql \li0\ri0\widctlpar
\tqc\tx4320\tqr\tx8640\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0 \fs24\lang1033\langfe1033\cgrid\langnp1033\langfenp1033 \sbasedon0 \snext16 \styrsid1516251 footer;}{\*\cs17 \additive \sbasedon10 \styrsid1516251 page number;}}
{\*\rsidtbl \rsid1516251\rsid4264116\rsid8656571\rsid8993742\rsid11566336\rsid12854629\rsid15010182}{\*\generator Microsoft Word 10.0.4524;}{\info{\title Special thanks to Jon Bauman for writing the first version of this document}{\author voigtjr}
{\operator voigtjr}{\creatim\yr2003\mo5\dy21\hr16\min49}{\revtim\yr2003\mo5\dy22\hr11\min38}{\printim\yr2003\mo5\dy21\hr16\min50}{\version4}{\edmins25}{\nofpages5}{\nofwords989}{\nofchars5638}{\*\company University of Michigan}{\nofcharsws6614}
{\vern16475}}\widowctrl\ftnbj\aenddoc\noxlattoyen\expshrtn\noultrlspc\dntblnsbdb\nospaceforul\hyphcaps0\horzdoc\dghspace120\dgvspace120\dghorigin1701\dgvorigin1984\dghshow0\dgvshow3\jcompress\viewkind1\viewscale100\nolnhtadjtbl\rsidroot11566336 \fet0
\sectd \linex0\sectdefaultcl\sftnbj {\header \pard\plain \s15\ql \li0\ri0\widctlpar\tqc\tx4320\tqr\tx8640\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid1516251 \fs24\lang1033\langfe1033\cgrid\langnp1033\langfenp1033 {\b\insrsid1516251
The Engine Engine Developer Coding Conventions\tab Revised }{\field{\*\fldinst {\b\insrsid1516251 DATE \\@ "M/d/yyyy" }}{\fldrslt {\b\lang1024\langfe1024\noproof\insrsid1516251 5/22/2003}}}{\b\insrsid1516251\charrsid1516251
\par }}{\footer \pard\plain \s16\ql \li0\ri0\widctlpar\tx2804\tqc\tx4320\aspalpha\aspnum\faauto\adjustright\rin0\lin0\itap0\pararsid1516251 \fs24\lang1033\langfe1033\cgrid\langnp1033\langfenp1033 {\insrsid1516251 \tab \tab Page }{\field{\*\fldinst {
\cs17\insrsid1516251 PAGE }}{\fldrslt {\cs17\lang1024\langfe1024\noproof\insrsid8656571 4}}}{\cs17\insrsid1516251 of }{\field{\*\fldinst {\cs17\insrsid1516251 NUMPAGES }}{\fldrslt {\cs17\lang1024\langfe1024\noproof\insrsid8656571 5}}}{\insrsid1516251
\par }}{\*\pnseclvl1\pnucrm\pnstart1\pnindent720\pnhang {\pntxta .}}{\*\pnseclvl2\pnucltr\pnstart1\pnindent720\pnhang {\pntxta .}}{\*\pnseclvl3\pndec\pnstart1\pnindent720\pnhang {\pntxta .}}{\*\pnseclvl4\pnlcltr\pnstart1\pnindent720\pnhang {\pntxta )}}
{\*\pnseclvl5\pndec\pnstart1\pnindent720\pnhang {\pntxtb (}{\pntxta )}}{\*\pnseclvl6\pnlcltr\pnstart1\pnindent720\pnhang {\pntxtb (}{\pntxta )}}{\*\pnseclvl7\pnlcrm\pnstart1\pnindent720\pnhang {\pntxtb (}{\pntxta )}}{\*\pnseclvl8
\pnlcltr\pnstart1\pnindent720\pnhang {\pntxtb (}{\pntxta )}}{\*\pnseclvl9\pnlcrm\pnstart1\pnindent720\pnhang {\pntxtb (}{\pntxta )}}\pard\plain \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0 \fs24\lang1033\langfe1033\cgrid\langnp1033\langfenp1033 {
\f1\fs20\insrsid15010182 Special thanks to Jon Bauman for writing the first version of this document.}{\f36\fs28\insrsid15010182
\par
\par }{\f36\fs28\insrsid4264116 Files}{\f1\fs20\insrsid4264116
\par
\par Put abstract classes in a file by themselves. Concrete classes with a common superclass should be in the same file together.
\par
\par Start each file with an initial comment (see below)
\par
\par }{\f36\fs20\insrsid4264116 Header Files}{\f1\fs20\insrsid4264116
\par
\par Do not define any methods in the header file.
\par }{\f1\fs20\insrsid11566336
\par Try to limit includes in header files to reduce re-compile time. Use forward declaration of classes and enumerations when possible.
\par }{\f1\fs20\insrsid4264116
\par Header files should not mix classes & functions. Any procedural functions should be declared in a separate header and have a corresponding source file with only function definitions.
\par
\par Header files should be in the following format
\par }{\f1\fs20\insrsid11566336
\par }{\f37\fs20\insrsid11566336 // $Id$
\par
\par #Pragma once
\par
\par /}{\f37\fs20\insrsid4264116 * ClassName
\par *
\par * Simple description of what the class does, and any other important stuff.
\par *
\par }{\f37\fs20\insrsid11566336 }{\f37\fs20\insrsid4264116 */
\par
\par #includes }{\f37\fs20\insrsid1516251 \tab \tab }{\f37\fs20\insrsid4264116
\par #include "more_includes.h"
\par
\par }{\f37\fs20\insrsid11566336 class C_ForwardDeclaration;
\par
\par }{\f37\fs20\insrsid4264116 class C}{\f37\fs20\insrsid11566336 _C}{\f37\fs20\insrsid4264116 lassName \{
\par
\par public:
\par
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0\pararsid11566336 {\f37\fs20\insrsid11566336 // constructors
\par // destructor
\par
\par // instance methods
\par // instance variables
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0 {\f37\fs20\insrsid4264116
\par // static methods
\par }{\f37\fs20\insrsid11566336 // static variables}{\f37\fs20\insrsid4264116
\par
\par protected:
\par
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0\pararsid11566336 {\f37\fs20\insrsid11566336 // constructors
\par
\par // instance methods
\par // instance variables
\par
\par // static methods
\par // static variables
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0 {\f37\fs20\insrsid4264116
\par private:
\par
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0\pararsid11566336 {\f37\fs20\insrsid11566336 // instance methods
\par // instance variables
\par
\par // static methods
\par // static variables
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0 {\f37\fs20\insrsid4264116 \};
\par }{\f1\fs20\insrsid4264116
\par }{\f1\fs20\insrsid11566336
\par }{\f36\fs20\insrsid4264116 Source Files}{\f1\fs20\insrsid4264116
\par
\par }{\f1\fs20\insrsid11566336 Ideally, every function in a source file should be }{\f1\fs20\insrsid15010182 preceded}{\f1\fs20\insrsid11566336 by comments describing its behavior:
\par
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0\pararsid15010182 {\f37\fs20\insrsid15010182\charrsid15010182 //------------------------------------------------------------
\par // Input
\par // Handle console input via windows messages
\par // This is for key-by-key input, NOT for commands
\par //------------------------------------------------------------}{\f37\fs20\insrsid15010182
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0 {\f1\fs20\insrsid11566336
\par Source files should follow the following format:}{\f1\fs20\insrsid4264116
\par
\par }{\f37\fs20\insrsid11566336 // $Id$}{\f37\fs20\insrsid4264116
\par
\par }{\f37\fs20\insrsid11566336 #include \'93classname.h\'94
\par #include \'93more_includes.h\'94 (two blank lines after last include)
\par
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0\pararsid11566336 {\f37\fs20\insrsid11566336
\par // const\rquote s and #defines (use const instead for constants when possible)
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0 {\f37\fs20\insrsid11566336
\par // extern declarations
\par
\par // static member definitions (two blank lines after static members)
\par
\par }{\f37\fs20\insrsid4264116
\par }{\f37\fs20\insrsid11566336 // }{\f37\fs20\insrsid4264116 Public methods }{\f37\fs20\insrsid11566336 (blank line between each)}{\f37\fs20\insrsid4264116
\par }{\f37\fs20\insrsid11566336
\par //}{\f37\fs20\insrsid4264116 Protected methods }{\f37\fs20\insrsid11566336 (blank line between each)}{\f37\fs20\insrsid4264116
\par }{\f37\fs20\insrsid11566336
\par // }{\f37\fs20\insrsid4264116 Private methods}{\f37\fs20\insrsid11566336 (blank line between each)}{\f37\fs20\insrsid4264116
\par }{\f37\fs20\insrsid11566336
\par }{\f37\fs20\insrsid4264116
\par }{\f36\fs28\insrsid4264116 Formatting
\par }{\f1\fs20\insrsid4264116
\par Put spaces around binary operators (except member access "." and "->" and scope resolution "::").
\par
\par }{\f37\fs20\insrsid4264116 i=j+5; // Wrong
\par i = j + 5; // Right
\par }{\f37\fs20\insrsid15010182
\par p_Pointer->member // Right
\par p_Pointer -> member // Wrong
\par }{\f1\fs20\insrsid4264116
\par Do not put a space between unary operators and their operands (including casts).
\par
\par }{\f37\fs20\insrsid4264116 i = - j; // Wrong
\par i = -j; // Right
\par
\par f = (float) d; // Wrong
\par f = (float)d; // Right }{\f1\fs20\insrsid4264116
\par
\par Put opening braces on the same line and closing braces on their own lines. Indent block code by 4 spaces (it's the default spacing for the tab key in MSVC++)
\par
\par }{\f37\fs20\insrsid4264116 int foo() \{
\par // do some stuff
\par \}
\par }{\f1\fs20\insrsid4264116
\par Indent long conditionals 8 spaces:
\par
\par }{\f37\fs20\insrsid4264116 if ((condition1 && condition2)
\par || (condition3 && condition4)) \{
\par doSomething();
\par \}
\par
\par }{\f1\fs20\insrsid4264116 Put the else on the same line as the closing brace of the corresponding if. The same goes for try-catch blocks}{\f1\fs20\insrsid15010182
. Putting the else on and the opening bracket on a new line is also ok, but keep the same format within the whole block.}{\f1\fs20\insrsid4264116
\par }{\f37\fs20\insrsid4264116
\par if (i == 5) \{
\par doThis();
\par \} else if (i == 6) \{
\par doThat();
\par \} else \{
\par doTheOtherThing();
\par \}
\par }{\f37\fs20\insrsid15010182
\par // Also acceptable:
\par if (y == z) \{
\par Act();
\par \}
\par else if (y == -y) \{
\par CalculateZ();
\par \}
\par else \{
\par Panic();
\par \}
\par }{\f1\fs20\insrsid4264116
\par }{\f1\fs20\insrsid8656571 Normally, one line \'93if\'94 blocks should use brackets.
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0\pararsid8656571 {\f37\fs20\insrsid8656571
\par if (p_Pointer) \{
\par p_Pointer->Modify();
\par \}
\par
\par }{\f1\fs20\insrsid8656571 However, the brackets may be removed if the body of the conditional is moved onto the same line.
\par }{\f37\fs20\insrsid8656571
\par if (errorFlag) throw Error(\'93Oh no!\'94); // Right
\par if (errorFlag2) // Wrong
\par throw Error(\'93My Bad!\'94);
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0 {\f1\fs20\insrsid8656571
\par }{\f1\fs20\insrsid4264116 Switch cases should have }{\f1\fs20\insrsid15010182 the next}{\f1\fs20\insrsid4264116 indent level }{\f1\fs20\insrsid15010182 respective to}{\f1\fs20\insrsid4264116 the switch keyword. }{\f1\fs20\insrsid15010182
Case bodies should have the next indent level respective to the case labels. }{\f1\fs20\insrsid4264116 Fall-through cases should be labeled with a comment
\par
\par }{\f37\fs20\insrsid4264116 switch (input) \{
\par }{\f37\fs20\insrsid15010182 }{\f37\fs20\insrsid4264116 case 1:
\par }{\f37\fs20\insrsid15010182 }{\f37\fs20\insrsid4264116 setToDefault();
\par }{\f37\fs20\insrsid15010182 }{\f37\fs20\insrsid4264116 // fall through
\par }{\f37\fs20\insrsid15010182 }{\f37\fs20\insrsid4264116 case 2:
\par }{\f37\fs20\insrsid15010182 }{\f37\fs20\insrsid4264116 playGame();
\par }{\f37\fs20\insrsid15010182 }{\f37\fs20\insrsid4264116 break;
\par }{\f37\fs20\insrsid15010182 }{\f37\fs20\insrsid4264116 default:
\par }{\f37\fs20\insrsid15010182 }{\f37\fs20\insrsid4264116 quit();
\par }{\f37\fs20\insrsid15010182 }{\f37\fs20\insrsid4264116 break;
\par \}
\par }{\f1\fs20\insrsid4264116
\par Use a blank space between keywords (if, for, while, try, catch, etc.) and parentheses, but not between function names and parentheses.
\par
\par }{\f37\fs20\insrsid4264116 if (stackPtr == NULL) \{\tab \tab // space }{\f37\fs20\insrsid15010182 because "if" is not a function,
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0\pararsid15010182 {\f37\fs20\insrsid15010182 // i}{\f37\fs20\insrsid4264116 t's an operator
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0 {\f37\fs20\insrsid4264116 panic(}{\f37\fs20\insrsid15010182 NOW}{\f37\fs20\insrsid4264116 );\tab \tab \tab // no space because "panic:" is a}{\f37\fs20\insrsid15010182
\par //}{\f37\fs20\insrsid4264116 function
\par \}
\par }{\f1\fs20\insrsid4264116
\par }{\b\f1\fs20\insrsid4264116\charrsid15010182 Declare only one variable per line}{\f1\fs20\insrsid4264116 so to allow room for comments. Put one space between variable modifiers and names, and try to line up comments with tabs.
\par
\par }{\f37\fs20\insrsid4264116 int level; // indentation level
\par int size; // size of table
\par }{\f1\fs20\insrsid4264116
\par When using pointers, }{\b\f1\fs20\insrsid4264116\charrsid15010182 put the asterisk next to the type}{\f1\fs20\insrsid4264116 .
\par }{\f37\fs20\insrsid4264116
\par int* length;
\par }{\f1\fs20\insrsid4264116
\par Refer to static methods and data with the class name, not with an instance variable.
\par
\par }{\f37\fs20\insrsid4264116 Ball player; // ball has instance variable velocity and
\par // static variable weight
\par
\par player.velocity; // }{\f37\fs20\insrsid15010182 Right}{\f37\fs20\insrsid4264116
\par player.weight; // Wrong
\par Ball::weight; // }{\f37\fs20\insrsid15010182 Right}{\f37\fs20\insrsid4264116
\par }{\f1\fs20\insrsid4264116
\par }{\f36\fs28\insrsid4264116 Naming
\par }{\f1\fs20\insrsid4264116
\par Classes should be named in mixed case with the first letter capitalized}{\f1\fs20\insrsid15010182 and prefix C_}{\f1\fs20\insrsid4264116 . No underscores }{\f1\fs20\insrsid15010182 except for the prefix}{\f1\fs20\insrsid4264116 .
\par
\par }{\f37\fs20\insrsid4264116 class }{\f37\fs20\insrsid15010182 C_}{\f37\fs20\insrsid4264116 Ball;
\par class }{\f37\fs20\insrsid15010182 C_}{\f37\fs20\insrsid4264116 WeakTile;
\par }{\f1\fs20\insrsid4264116
\par Global functions should be verbs in mixed case with the first letter lower case. No underscores or prefixes.
\par
\par }{\f37\fs20\insrsid4264116 run();
\par getVelocity();
\par setAcceleration();
\par }{\f1\fs20\insrsid4264116
\par Methods (functions that are members of a class) should be verbs in mixed case with the first letter upper case. No underscores or prefixes.
\par
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0\pararsid4264116 {\f37\fs20\insrsid4264116 Class C_Car \{
\par Public:
\par Run();
\par GetVelocity();
\par SetAcceleration();
\par \}
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0 {\f1\fs20\insrsid4264116
\par Variables should be nouns in mixed case with the first letter lower case. No underscores or prefixes except in special cases outlined below. One-letter variable names should be restricted to loop counters. Handl
e variables should end with Hnd or Handle. In general, prefer words over abbreviations when they do not make the variable name prohibitively long.
\par
\par }{\f37\fs20\insrsid4264116 int height;
\par float absolutePosition;
\par }{\f37\fs20\insrsid8993742 double* p_F}{\f37\fs20\insrsid4264116 requency;
\par HINSTANCE intstanceHnd;}{\f37\fs20\insrsid12854629
\par
\par }{\f1\fs20\insrsid4264116 Global variables should begin with a g_ prefix. Pointers should begin with p_. The first letter after the prefix should be capitalized.
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0\pararsid4264116 {\f37\fs20\insrsid4264116
\par int g_Height;\tab \tab \tab // global variable
\par double* p_Frequency;\tab \tab // local pointer
\par double* gp_Temperature\tab \tab // global pointer
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0 {\f1\fs20\insrsid4264116
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0\pararsid12854629 {\f1\fs20\insrsid12854629 Although
array variables are technically pointers, if they are often used with subscripts (as opposed to the * or -> operators) then the p_ prefix should not be used.
\par }{\f37\fs20\insrsid12854629
\par int array[6];
\par }{\f1\fs20\insrsid12854629
\par }\pard \ql \li0\ri0\nowidctlpar\faauto\rin0\lin0\itap0 {\f1\fs20\insrsid4264116 Constants should be nouns in uppercase with words separated by underscores.
\par
\par }{\f37\fs20\insrsid4264116 #define GAME_PORT 9393\tab \tab // avoid when practical
\par const int MAX_VELOCITY = 10;
\par
\par }{\f36\fs28\insrsid4264116 Misc
\par }{\f1\fs20\insrsid4264116
\par To label something that is broken, or should potentially be changed put "FIXME" in a comment.
\par
\par }{\f37\fs20\insrsid4264116 bind(socket);\tab // FIXME: should handle errors but doesn't}{\f1\fs20\insrsid4264116
\par
\par }}