1,072
edits
Octave style guide: Difference between revisions
m
→Indentation
(→Quoted Strings: new section) |
m (→Indentation) |
||
| (28 intermediate revisions by 4 users not shown) | |||
| Line 11: | Line 11: | ||
=== Line Length === | === Line Length === | ||
There is no fixed line length. In general, strive for clarity and readability and use your own judgement. | |||
Everyone has access to monitors with more than 80 columns, but even so, exceptionally long lines can be hard to read. However, keeping code together on a line that is logically one unit does improve readability. | |||
=== Indentation === | === Indentation === | ||
| Line 19: | Line 19: | ||
Use only spaces, and indent 2 spaces at a time. | Use only spaces, and indent 2 spaces at a time. | ||
Absolutely '''do not use tabs''' in your code. You should probably set your editor to emit spaces when you hit the tab key. | |||
You should probably set your editor to emit spaces when you hit the tab key. | |||
=== Whitespace === | === Whitespace === | ||
===== Function Calls ===== | |||
When calling functions, put spaces after commas and before the calling | When calling functions, put spaces after commas and before the calling | ||
parentheses, like this: | parentheses, like this: | ||
<pre>x = max (sin (y+3), 2);</pre> | <pre>x = max (sin (y + 3), 2);</pre> | ||
An exception are matrix or cell constructors: | An exception are matrix or cell constructors: | ||
| Line 38: | Line 39: | ||
Here, putting spaces after {{codeline|sin}}, {{codeline|cos}} would result in a | Here, putting spaces after {{codeline|sin}}, {{codeline|cos}} would result in a | ||
parse error. | parse error. | ||
===== Indexing Expressions ===== | |||
For indexing expressions, do ''not'' put a space after the | For indexing expressions, do ''not'' put a space after the | ||
| Line 49: | Line 52: | ||
<pre>A([1:i-1;i+1:n], XI(:,2:n-1))</pre> | <pre>A([1:i-1;i+1:n], XI(:,2:n-1))</pre> | ||
===== Matrix Definition ===== | |||
When constructing matrices, prefer using the comma rather than the space to | When constructing matrices, prefer using the comma rather than the space to | ||
| Line 58: | Line 63: | ||
</pre> | </pre> | ||
However, if the matrix is large or the indentation makes it clear the comma | However, if the matrix is large or the indentation makes it clear then the comma | ||
may be dropped. | may be dropped. | ||
| Line 64: | Line 69: | ||
prices = [ 1.01 2.02 3.03 | prices = [ 1.01 2.02 3.03 | ||
44.04 55.05 6.06]; | 44.04 55.05 6.06]; | ||
</pre> | |||
There is no need to include semicolons to define rows when a newline is used instead. | |||
===== Arithmetic Operators ===== | |||
Do include spaces around all binary arithmetic operators, for example | |||
<pre> | |||
x = 1 / (1 + y) ^ 2; | |||
</pre> | |||
An exception is for extremely simple expressions like | |||
<pre>n+1</pre> | |||
In particular, simple expressions used as an argument to a function or as part of an indexing expression usually look better without extra spacing. For example, you may write | |||
<pre> | |||
x(1:end-1) | |||
</pre> | |||
Another exception is for complex arithmetic expressions. It ''may'' improve readability to omit spaces around higher precedence operators, for example | |||
<pre> | |||
z = cat (dim, (x2.*y3 - x3.*y2), (x3.*y1 - x1.*y3), (x1.*y2 - x2.*y1)); | |||
</pre> | </pre> | ||
| Line 70: | Line 101: | ||
When you encounter an error condition, call the function {{codeline|error}} | When you encounter an error condition, call the function {{codeline|error}} | ||
(or {{codeline|print_usage}}). The {{codeline|error}} and {{codeline|print_usage}} functions | (or {{codeline|print_usage}}). The {{codeline|error}} and {{codeline|print_usage}} functions | ||
do not return. | do not return. | ||
with the name of the function that generated it. For example: | |||
It is customary to prefix the error message with the name of the function that generated it. For example: | |||
<pre>error ("my_cool_function: input A must be a matrix");</pre> | <pre>error ("my_cool_function: input A must be a matrix");</pre> | ||
Octave has several functions that produce error messages according | Because the function call to {{codeline|error}} is one code unit, prefer keeping the message on one line even if the message itself is long. | ||
to the Octave guidelines. Consider using {{codeline|inputParser}} | |||
Octave has several functions that produce error messages according to the Octave guidelines. Consider using {{codeline|inputParser}} | |||
and {{codeline|validateattributes}}. | and {{codeline|validateattributes}}. | ||
== Naming == | == Naming == | ||
Use lowercase names if possible. Uppercase is acceptable for variable | Use lowercase names if possible. Uppercase is acceptable for variable names consisting of 1-2 letters. Do not use mixed case (a.k.a. CamelCase) names. | ||
names consisting of 1-2 letters. Do not use mixed case names. | |||
names must be lowercase. Function names are global, so choose them | Function names must be lowercase. Function names are global, so choose them wisely. | ||
wisely. | |||
=== General naming functions === | === General naming functions === | ||
| Line 90: | Line 122: | ||
=== Function names === | === Function names === | ||
For most public functions we are limited by Matlab compatibility. Use | For most public functions we are limited by Matlab compatibility. Use whatever name Matlab chose. | ||
whatever name Matlab | |||
For functions that are not present in Matlab, favor the use of underscores. | |||
For example, {{codeline|base64_decode}}, {{codeline|common_size}}, or {{codeline|compare_versions}}. | |||
There are exceptions to this: | |||
; Matching C functions | ; Matching C functions | ||
| Line 103: | Line 135: | ||
=== Variable names === | === Variable names === | ||
Avoid reusing the names of other functions as local variable names. For | |||
example, avoid naming local variables {{codeline|abs}}, | |||
{{codeline|log}}, or {{codeline|pow}}. These names might be used later to try to call the function of that name, but instead will refer to a local variable, leading to very confusing errors. | |||
An exception is the use of {{codeline|i}} and {{codeline|j}} as loop indices. | |||
If a function has nothing to do with complex arithmetic, it is common and | |||
acceptable to use {{codeline|i}} and {{codeline|j}} as local variables in | |||
for loops. | |||
== Quoted Strings == | == Quoted Strings == | ||
| Line 159: | Line 200: | ||
== ! operator == | == ! operator == | ||
The Octave operator | * The Octave operator <code>!</code> should be used for logical negation, rather than <code>~</code>. | ||
* The negation operator is written with a space between the operator and its target, e.g., <code>! A</code>. | |||
and its target, e.g., | * For comparisons use <code>!=</code> instead of <code>~=</code>. | ||
== Comments == | == Comments == | ||
| Line 168: | Line 208: | ||
=== # or % === | === # or % === | ||
Always use {{Codeline|#}} to write comments. | Always use {{Codeline|#}} to write comments for Octave code. Only use {{Codeline|%}} if code must run in a dual Matlab/Octave environment. | ||
Absolutely do not use {{codeline|%#}} or mix {{codeline|%}} and {{codeline|#}} | Absolutely do not use {{codeline|%#}} or mix {{codeline|%}} and {{codeline|#}} | ||
| Line 218: | Line 258: | ||
The preferred comment mark for places that may need further attention is | The preferred comment mark for places that may need further attention is | ||
with {{codeline|FIXME:}} comments. | with {{codeline|FIXME:}} comments. | ||
[[Category:Development]] | |||