Coding conventions

Some coding conventions for the MatGeom project.

Table of Contents File names Functions Classes Test functions Code Punctuations Structuration of code Function headers General guidelines Header line Syntax Other fields Authoring information Example Help files Links

File names

no limitation in the size of file names
extension is ".m".

Functions

Function names use lower camel case: start with a lower case, words are separated by upper case. Example: `myTinyFunction.m`
Function names may use a prefix to better identify a functional group. Example: `meshXXX` indicates a function operating on a mesh.
Function names should start by verbs. Examples: `drawPoint`, `clipPolygon`, `smoothMesh`... When the function consists in computing a property from a data structure, a name can be used. Example: `polygonArea`, `meshCentroid`
Conversion functions use 'To' between radicals. Ex: `ellipseToPolygon`, `edgeToLine`, `circleArcToPolyline`...

Classes

(not used for the moment, but in case of future use)

Class names use upper camel case: MyClassName.
Class methods are either verbs, or substantive, to avoid repetitive "getXXX" functions.

Test functions

When performing unit tests, the convention is to prefix the name of the function under test by the prefix `test_`. This allows to include the name of the original function without case modification.

Code

The code should be rather "light". Some general guidelines:

one instruction per line if possible
one space before and after affectation mark "="
one space before and after conditional marks: "==", "~=", ">", "<="...
parens may be avoided when possible
no space between function name and opening paren

Punctuations

semicolons are not necessary after "end" statements
semicolons are welcome after "return" statement (this is an instruction)

Structuration of code

It is a good practice to write "functional blocs", composed of several lines, that focus on a specific task, together with a small comment describing the task.

Control structures (for-loops, conditional tests...) are indented with four spaces. Tabulations have to be avoided, as they appear differently depending on the editors.

It is better to avoid writing test or for-loops in a single line.

Example:

    % Data initialisation
    data = zeros(1, N);
    for i = 1:N
        value = getInitValue(i);
        data(i) = computeNewValue(value);
    end

Function headers

General guidelines

Header line

The first line contains the function declaration.

The second line is a comment that summarizes the function:

it may start by function name in upper case (to facilitate inclusion in Contents report)
it contains a short summary of the function, starting with an infinite verb, and starting with an upper case digit (to homogeneize Contents.m files)
first header line should finish by a dot.

Syntax

The remaining header contains a description of the function with one or more syntax(es). For each syntax, it is advised to give a typical command line, then the explanations after a line break. Explanations uses conjugate verbs. Input and output arguments may be given in upper case, to facilitate their reading, and avoid possible ambiguities with function names.

Other fields

It is useful to give one or two (or more!) example use case.

It is also useful to complete the "See Also" section.

Authoring information

After the header (separated by a blank line), the file may contain additional information such as the name of author, with date of creation. It may also contains author affiliation (company ...), and date of last revision.

Example

Sample header for a function called "demoFunction":

    function res = demoFunction(x, n)
    % Compute a sample function of x and n.
    %
    % RES = demoFunction(X, N)
    % Computes the N-th power of the number X.
    %
    % RES = demoFunction(X, N, METHOD)
    % Specifies the method to use. METHOD can be one of:
    % 'normal': use the normal method
    % 'optimized': use the optimized method

Help files

Some files are used to gather information about functions that work on similar data structures, and can be seen as "sub-sections" of the Contents.m located in the same directory. For example, the `lines2d.m` describes functions operating on straight lines, rays and line segments.

For these files, as well as the `Contents.m` files, it is useful to add a command `help(mfilename)`. Then the help is displayed if ones tries to run the file.