diff options
Diffstat (limited to 'cvs/cvsweb.cgi/code/nel/doc/coding.dxt?rev=1.7&content-type=text/x-cvsweb-markup&sortby=author/index.html')
| -rw-r--r-- | cvs/cvsweb.cgi/code/nel/doc/coding.dxt?rev=1.7&content-type=text/x-cvsweb-markup&sortby=author/index.html | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/cvs/cvsweb.cgi/code/nel/doc/coding.dxt?rev=1.7&content-type=text/x-cvsweb-markup&sortby=author/index.html b/cvs/cvsweb.cgi/code/nel/doc/coding.dxt?rev=1.7&content-type=text/x-cvsweb-markup&sortby=author/index.html new file mode 100644 index 00000000..f02171b6 --- /dev/null +++ b/cvs/cvsweb.cgi/code/nel/doc/coding.dxt?rev=1.7&content-type=text/x-cvsweb-markup&sortby=author/index.html @@ -0,0 +1,185 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML> +<HEAD><style> A { color:black }</style> +<!-- hennerik CVSweb $Revision: 1.93 $ --> +<TITLE>code/nel/doc/coding.dxt - view - 1.7</TITLE></HEAD> +<BODY BGCOLOR="#eeeeee"> +<table width="100%" border=0 cellspacing=0 cellpadding=1 bgcolor="#aaaaaa"><tr valign=bottom><td><a href="coding.dxt?sortby=author"><IMG SRC="http://www.nevrax.org/inc/img/picto-up.gif" ALT="[BACK]" BORDER="0" WIDTH="14" HEIGHT="13"></a> <b>Return to <A HREF="coding.dxt?sortby=author">coding.dxt</A> + CVS log</b> <IMG SRC="http://www.nevrax.org/inc/img/picto-news.gif" ALT="[TXT]" BORDER="0" WIDTH="13" HEIGHT="15"></td><td align=right><IMG SRC="http://www.nevrax.org/inc/img/picto-dir.gif" ALT="[DIR]" BORDER="0" WIDTH="15" HEIGHT="13"> <b>Up to <a href="/cvs/cvsweb.cgi/?sortby=author">Nevrax</a> / <a href="/cvs/cvsweb.cgi/code/?sortby=author">code</a> / <a href="/cvs/cvsweb.cgi/code/nel/?sortby=author">nel</a> / <a href="/cvs/cvsweb.cgi/code/nel/doc/?sortby=author">doc</a></b></td></tr></table><HR noshade><table width="100%"><tr><td bgcolor="#ffffff">File: <a href="/cvs/cvsweb.cgi/?sortby=author">Nevrax</a> / <a href="/cvs/cvsweb.cgi/code/?sortby=author">code</a> / <a href="/cvs/cvsweb.cgi/code/nel/?sortby=author">nel</a> / <a href="/cvs/cvsweb.cgi/code/nel/doc/?sortby=author">doc</a> / <a href="/cvs/cvsweb.cgi/code/nel/doc/coding.dxt?sortby=author">coding.dxt</a> (<A HREF="/cvs/cvsweb.cgi/~checkout~/code/nel/doc/coding.dxt?rev=1.7&sortby=author" target="cvs_checkout" onClick="window.open('/cvs/cvsweb.cgi/~checkout~/code/nel/doc/coding.dxt?rev=1.7','cvs_checkout','resizeable,scrollbars');"><b>download</b></A>)<BR> +Revision <B>1.7</B>, <i>Fri Dec 1 15:57:25 2000 UTC</i> (19 months, 1 week ago) by <i>lecroart</i> +<BR>Branch: <b>MAIN</b> +<BR>CVS Tags: <b>proto_0_2, proto_0_1, nel_0_4, nel_0_3, nel_0_2, georges_v2, demo_0_1, HEAD</b><BR>Changes since <b>1.6: +0 -1 + lines</b><PRE> +no message +</PRE> +</td></tr></table><HR noshade><PRE>/** + +\page codinghowto Coding and presentation conventions +\author Vincent Archer +\author Vianney Lecroart + +\section introcode Introduction + +This document defines and formalises the presentation and redaction of all source +files in the NeL platform. A strict adherence to these conventions is required +to ensure a readable and understandable code. + +\section filename File naming + +There are very few restrictions on file names and locations. The following rules are +expected: + +- Files must end with the appropriate suffix: + - \c .cpp for ANSI C++ code + - \c .c for ANSI C code + - \c .h for included declarations + - \c .asm for assembly-level files + - \c .dxt for doxygen documentation source without code. +- Significant, english, file names. Length is not capped, but should be kept within + resonable bounds. +- No spaces or uppercase letters. If the name is composed of separate, discrete words, + the underline character is used instead of space as the separator. + +\section fileloc File locations + +A quick check of the CVS source directory will show how files are organised within the +source tree. The sources are organised in two levels. The first level specifies which +part of the platform the source belongs to + +- \c nel +- \c client +- \c server + +The second level specifies which logical part the file belongs to: + +- \c network +- \c ai +- \c 3d +- \c database +- \c file +- \c system +- \c misc + +This applies to basic source as well as include files, who are in a separate include +tree and never along their source code files. Thus, an include declaration would be + +\code +#include "nel/misc/steam.h" +\endcode + +\section filehdrs File header + +All code files must begin with a specific header. The model of that header is defined +in Headers.txt in the documentation directory. It is recommended that people include +that file immediately when starting a new file. + +\section basetype Base types + +- Integral types + - The first letter specifies \c 's' for signed integers or \c 'u' for unsigned integers. + It is not possible to specify a 'dont care sign' integer + - The next three letters are \c 'int' + - The type ends with the number of bits used to represent the integral type, or + nothing to specify an integer that is *at least* 32 bits wide + - Examples: \c uint8 (unisgned 8 bits integer), \c sint64 (signed 64 bits integer), \c sint + (signed integer of at least 32 bits) +- Classic types + - \c float (32 bits floating point number, use is discouraged) + - \c double (64 bits floating point number) + - \c bool (an equivalent to the hypothetical uint1 type) + - \c void (empty type) + - \c char (ASCII character, not to be confused with uint8/sint8) + - \c uchar (Unicode character, on 16 bits) + - \c string (ASCII string) + - \c ustring (Unicode character string) + +As a general rule, the classic and sloppy use of \c short / \c int / \c long is proscribed, as is using +a \c 'char' to represent a 8-bit number, unless this is required to call an external API. + +\section nameconv Naming convention + +All elements will be in their own namespace, which is short, in all uppercase, and consist of +a two letter code (\c NL for NeL), followed by the directory name. Thus an element of the NeL +3D library will be declared in the \c NL3D namespace. + +The following conventions are applied to names within these namespaces: + +- All names must include one or more english words which have relevance to the entity + being named. If multiple words are used for a more descriptive naming, all words begin + with an uppercase letter, the underscore character is not used to separate words (e.g. + \c Word, \c FullWord, \c ComplexQualifiedWord) +- Class methods start with a lowercase character, e.g. \c load(), \c store(), \c giveMoney() +- Public attributes of a class start with an uppercase, e.g. Layer, Set, ResourceType +- Private and Protected attributes of a class start with an underscore character, then an + uppercase letter, e.g. \c _State, \c _ResourceKind +- Local variables and parameters start with a lowercase letter, e.g. \c size, \c x, \c i +- Structures and Classes start with the uppercase \c C letter, then the name starting with + an uppercase letter as well, e.g. \c CTexture, \c CMyClass +- Interfaces start with the uppercase \c I letter, then the name starting with an + uppercase letter as well +- Iterators start with the prefix \c 'It' (uppercase I, lowercase t), then the name starting + with an uppercase letter, e.g. \c ItTexture +- Other types, enums and the like are prefixed with an uppercase \c T, then the name. +- Globals function and values are prefixed by their namespace values, then follow the + standard conventions, e.g. \c NLAI::createAttribut(), \c NLAI::ReactiveState +- Preprocessor constants are in full uppercase, and consist of the namespace, an underscore + character, then a name, with underscores as separators, e.g. \c NLAI_MACRO, \c NL_OS_UNIX + +Note that there is no difference between variables and constants. + +\section codestyle Coding style + +\subsection indents Indentation + +A strong suggestion is to set your tabulation marks to 4 characters, rather than the usual 8. +Indentation is always done using tabulations, never with spaces. Make sure your text editor +does not replace tabulations with spaces. + +If possible, function, members and variable lists should align the first character of all +their names. + +\subsection braces Braces + +Source code is written using a flat style. In this style, the opening and closing curly braces +are placed on separate lines (never with code), and at the same indentation as the precedeing +defining element, while the content of the block enclosed between the braces is indented once +from the source. Your code source should look like this: + +\code +class CDummy +{ + void dummy (uint32 b) + { + if (b == 0xDEADBEEF) + { + ... + } + } +}; +\endcode + +\subsection commenting Comments + +Comments may use either the C++ style comments \c //, or the more classic C commenting method. If +possible, the source must be heavily commented, and as many comments as possible must conform +to the Doxygen commenting methods, to be extracted and reused as software documentation. + +Comment "separators" will be made with a line of repeated star \c '*' characters. You should not +use more than 50 stars to separate. + +The practice of comment blocks, i.e. comments where each line begins and end with a star +character, to create a "text block" is proscribed. + +\section final Final coding recommendations + +Even if most of these are obvious recommendations, it is useful to restate these basic +principles: + +- The use of \c #define must be restricted. Constants values and macro functions can be expressed + directly in C++ using constants and inline functions, and do not require pre-processor + definitions. +- The \c 'using \c namespace' declaration is proscribed in includes, unless it is in a well + defined scope. +- Include files paths, and all other file names should use the \c '/' character as the directory + separator, for portability purposes. +*/ +</PRE>
\ No newline at end of file |