CodingConventions

Description of style:

Terminology

The capitalized key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, RFC 2119 (http://xml.resource.org/public/rfc/html/rfc2119.html).

Rules:

Filenames

• All filenames within the library SHOULD have name part not longer than eight characters and extension part not longer than three characters (i.e. filenames SHOULD meet FAT16 requirements). There are two exceptions: the first is for all the Makefiles, and the other is for these files which represent library functions such as, for example, MAKEHASHTABLE (the file is named lisp/library/hsh/makehashtable.cpp). The former may be the one to change.

Symbols in source code

• Source code MUST be in ASCII encoding (i.e. no symbols with codes greater than 127 and no myltibyte symbols are allowed). There MUST be no TAB symbols in code. (If you have some, tell vim :set et^M:%ret! before committing file to InteLib repository; if you're in doubt, tell it to vim anyway; if you're in doubt and want to check, tell vim :se list).
• Macro SHOULD only be used for conditional compile directives and to define compile-time options, and MUST be named by all-uupercase identifiers starting with INTELIB_ prefix.
• Header files SHOULD have a wrapper of ifdef,define,...endif sentry, which MUST be named INTELIB_FILENAME_EXT_SENTRY (where FILENAME is uppercase version of header filename and EXT is uppercase version of header file extension).
• All class names and method names except for exception class names MUST obey wikiword standard. Exception class names MUST obey naming IntelibX_exception_name (where exception_name is description of exception type all in lowercase with words separated with underscores, e.g IntelibX_not_a_variable).
• Classes directly or indirectly inherited from SExpression and SReference form two (parallel) hierarchies; all classes from these two hierarchies must have a prefix in their names which determines the library layer to which the class belongs:
  • Classes related to the S-expressions as such, MUST be named starting with S (such as SExpression, SReference, etc)
  • Classes related to the Lisp computational model MUST be named starting with L (such as LReference, LExpressionPackage, etc.);
  • names of classes related to Scheme MUST start with Sch prefix
• Class name MUST contain word Expression if it is directly or indirectly inherited from class SExpression. Class name MUST NOT contain word Expression if it is not inherited from class SExpression directly or indirectly.
• Class of a smart pointer (that is, a SReference descendor) intended to work with a specific type of SExpression, MUST be named just like the respective S-expression class, with the word Expression ommited and the suffix Ref added; class of a master pointer designed for a specific expression type, if any, SHOULD be inherited directly from the respective smart pointer and be named just like it, without the Ref suffix. E.g., if the S-expression is represented with SExpressionLabel, then its smart pointer is named SLabelRef and the master pointer is named SLabel.
• Classes outside these two hierarchies are named with a longer prefix: Intelib for the lower layer, Lisp for the Lisp computational mode, Scheme for the Scheme computational mode. E.g., the prototype of the continuation-based machine is named IntelibContinuation?, and has two children: the LispContinuation? and the SchemeContinuation classes. This rule doesn't apply to the exception class hierarchy: all the exceptions are always named IntelibX?_the_exception.
• Fields within classes MUST be all lowercase and MAY have underscore symbols in their inner positions (not the first nor the last symbol).
• Function arguments SHOULD be named afield if the argument has same meaning as field in class (e.g. field initialization or alternative field value for computations).

Indentation and line breaks

• Indentation style is the following:
  • There are two cases in which curly brackets are dropped (i.e. MUST be dropped) to next line. First is a function implementation outside of a class body; and the second is in a construct (like if, while, for etc) which has its header broken into several lines. In both cases curly brackets MUST be the only non-space character on the line and code inside brackets MUST be indented to four spaces
  • In all other cases opening curly bracket MUST stay on same line with header of block it delimits (e.g. class definition, if/while statement header etc.), closing curly bracket MUST stay on the same column as header of block and contents of block MUST be shifted by four spaces relative to that column.
• Line witdth SHOULD be small enough to fit in screen of standard (80x24) terminal in vim with :se nu and MUST always fit nicely in vim with :se nonu or cat output. That is, it each line SHOULD be shorter than 72 characters and MUST be shortet than 80 characters. (Though one MAY have line of length between 73 and 79 if it would beak ugly).
• Line breaks MUST obey the following rules:
  • TODO: write rules here

See also

You SHOULD be able to use russian version of this page also at RuCodingConventions?. :-)

Comments

Ohw! It looks like my use of terms MUST, SHOLD, etc. breaks the state of RFC2119! That is bad! Or... Or we may say that we use _some_tool_ for automatic code processing which relies on that stlye. In that case it's ok :-) -- Dendik