Style guide for the COBRA Toolbox (MATLAB code).

COBRA Style Guide

1) Indentation: No tabs should be used. An indentation should be four spaces in length only.
Many editors have a way to insert the appropriate number of spaces when the tab key is pressed;
please see your editor's documentation. MATLAB's own editor adopts this convention by default.

2) Comments on function inputs (including optional inputs) and outputs should be explained 
in detail directly below the function signature. This should be done in the following sections:

INPUT

OPTIONAL INPUTS

OUTPUT

Please see an example, such as optimizeCbModel.m.

3) A list of modifications to the file should be maintained immediately below the I/O
description mentioned above, along with the author and date of the change. 
Please see an example, such as optimizeCbModel.m.

4) Leave a single space around all algebraic symbols and assignment symbols.
This is more of a recommendation than a requirement, but for short expressions,
it should be "a <= b" or "a = 7" or "x + 1", NOT "a<=b", "a=7", or "x+1".
While this is not required for boolean operators, it is preferred.
A longer expression may leave out some spaces around the operations that
take precedence, e.g.:
myVar = x*y*z + w
not:
myVar = x*y*z+w
and certainly not:
myVar = x * y * z+w.

5) Code blocks and variable names should be appropriately commented.

Certainly not every variable name needs to be commented, such as iterators,
but it is best to err on the side of verbosity.

6) For simple variable or function names, unless it involves a acronym, lower case should suffice.

For longer variable names, lowerCamelCase is the standard.

7) Optional arguments should be checked with the 'exist' keyword (see optimizeCbModel.m for an example),
rather than testing with the 'nargin' keyword, which is far less flexible.

8) Rather than having long source lines, try to have at most 70 characters per line, 
and use line continuations with "...". For example, rather than doing:

myVar = (some long expression) + (some other long expression)

do:

myVar = (some long expression) + ...
        (some other long expression)
        

This has the advantage of making code MUCH easier to read in multi-pane text editors.
Remember, as with commenting, you are not the only person reading your code.

9) It is best to use a space after a comma in an argument list:

myVal = myFun(arg1, arg2, arg3)

NOT: 

myVal = myFun(arg1,arg2,arg3)

You may be tempted to condense a line in this fashion to save space,
so as to avoid breaking up the line. Remember, there is no prize
for writing fewer lines of code, but everyone benefits from improved
clarity. In a long argument list, it is much easier to see the index
of arguments if they are split with space and on multiple lines.

10) It is highly advisable to put an end statement at the end of functions,
particularly in files with multiple functions. Also, in this case, it 
should be labeled:
function myOut = myFun(...)
doStuff();
end % of myFun

Also, inside of functions, it is find to not indent the first level of code.
So if you have a while loop as the top level of your function, it may look like
this:
function myOut = myFun(...)
while 1==1
    doStuff();
end % of while 1==1
end % of myFun

This exception to the rule for indentation may not look quite as pretty, but,
it prevents excessive indentation while making it even more clear that we are
at the end of the function. Relatedly, labels of long loops with an "end" can
and should also be labeled, as above

=================
Minor Points

In general, vectorized implementations should be used for efficiency in MATLAB.
For a tutorial on vectorization in MATLAB, see:
http://www.mathworks.com/help/matlab/matlab_prog/vectorization.html

This is a good style guide, too: http://www.datatool.com/downloads/matlab_style_guidelines.pdf

I like the suggestions at http://www.mathworks.com/help/matlab/matlab_prog/improve-code-readability.html

Specifically, I like code folding, and I generally try to keep lines shorter than the 75 column text limit. I often use ... to wrap longer lines.

I also like to include references to specific papers where possible in the introductory comments.

Also, if we want optimizeCbModel.m to be the template for future COBRA code, we should be sure it looks really good! (I haven't looked at it lately)