1,072
edits
Octave style guide: Difference between revisions
m
→Indentation
m (→Error messages) |
m (→Indentation) |
||
| (20 intermediate revisions by the same user not shown) | |||
| Line 13: | Line 13: | ||
There is no fixed line length. In general, strive for clarity and readability and use your own judgement. | 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. | 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 | ||
| 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 65: | Line 70: | ||
44.04 55.05 6.06]; | 44.04 55.05 6.06]; | ||
</pre> | </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 | Do include spaces around all binary arithmetic operators, for example | ||
| Line 72: | Line 81: | ||
</pre> | </pre> | ||
An exception is for extremely simple expressions like <pre>n+1</pre> | An exception is for extremely simple expressions like | ||
particular | |||
expression. For example, you may write | <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> | <pre> | ||
| Line 80: | Line 91: | ||
</pre> | </pre> | ||
Another exception is for complex arithmetic expressions. It may improve | Another exception is for complex arithmetic expressions. It ''may'' improve readability to omit spaces around higher precedence operators, for example | ||
readability to omit spaces around higher precedence operators, for example | |||
<pre> | <pre> | ||
| Line 91: | 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> | ||
Because the function call to | 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. | ||
Octave has several functions that produce error messages according | Octave has several functions that produce error messages according to the Octave guidelines. Consider using {{codeline|inputParser}} | ||
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 113: | 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 128: | Line 137: | ||
Avoid reusing the names of other functions as local variable names. For | Avoid reusing the names of other functions as local variable names. For | ||
example, | example, avoid naming local variables {{codeline|abs}}, | ||
{{codeline|log}}, or {{codeline|pow}}. These | {{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. | An exception is the use of {{codeline|i}} and {{codeline|j}} as loop indices. | ||
| Line 200: | 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|#}} | ||