1,072
edits
Octave style guide: Difference between revisions
m
→Indentation
m (→Function names) |
m (→Indentation) |
||
| (11 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. However, keeping code together on | 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 === | ||
| Line 64: | 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 86: | Line 85: | ||
<pre>n+1</pre> | <pre>n+1</pre> | ||
In particular, | 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 92: | Line 91: | ||
</pre> | </pre> | ||
Another exception is for complex arithmetic expressions. It may improve readability to omit spaces around higher precedence operators, for example | Another exception is for complex arithmetic expressions. It ''may'' improve readability to omit spaces around higher precedence operators, for example | ||
<pre> | <pre> | ||
| Line 102: | 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> | ||
| Line 109: | Line 109: | ||
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. | 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 124: | 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 chose. | |||
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 140: | Line 138: | ||
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, avoid naming local variables {{codeline|abs}}, | example, avoid naming local variables {{codeline|abs}}, | ||
{{codeline|log}}, or {{codeline|pow}}. These names might be used later to try to call the function | {{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. | ||