Skip to content

Instantly share code, notes, and snippets.

@bbarker
Last active December 23, 2015 00:09
Show Gist options
  • Save bbarker/6551884 to your computer and use it in GitHub Desktop.
Save bbarker/6551884 to your computer and use it in GitHub Desktop.
Style guide for the COBRA Toolbox (MATLAB code).
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
@bheavner
Copy link

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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment