Editing Octave style guide
Jump to navigation
Jump to search
The edit can be undone. Please check the comparison below to verify that this is what you want to do, and then publish the changes below to finish undoing the edit.
Latest revision | Your text | ||
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 one 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 | We use spaces for indentation. Absolutely **do not use tabs** in your code. | ||
You should probably set your editor to emit spaces when you hit the tab key. | |||
=== Whitespace === | === Whitespace === | ||
Line 63: | Line 64: | ||
</pre> | </pre> | ||
However, if the matrix is large or the indentation makes it clear | However, if the matrix is large or the indentation makes it clear the comma | ||
may be dropped. | may be dropped. | ||
Line 70: | Line 71: | ||
44.04 55.05 6.06]; | 44.04 55.05 6.06]; | ||
</pre> | </pre> | ||
===== Arithmetic Operators ===== | ===== Arithmetic Operators ===== | ||
Line 81: | Line 80: | ||
</pre> | </pre> | ||
An exception is for extremely simple expressions like | An exception is for extremely simple expressions like <pre>n+1</pre>, in | ||
particular when used as an argument to a function or as part of an indexing | |||
<pre>n+1</pre> | expression. For example, you may write | ||
<pre> | <pre> | ||
Line 91: | Line 88: | ||
</pre> | </pre> | ||
Another exception is for complex arithmetic expressions. | Another exception is for complex arithmetic expressions. It may improve | ||
readability to omit spaces around higher precedence operators, for example | |||
<pre> | <pre> | ||
Line 101: | Line 99: | ||
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. It is customary to prefix the error message | ||
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 106: | ||
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 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 names consisting of 1-2 letters. Do not use mixed case | Use lowercase names if possible. Uppercase is acceptable for variable | ||
names consisting of 1-2 letters. Do not use mixed case names. Function | |||
names must be lowercase. Function names are global, so choose them | |||
wisely. | |||
=== General naming functions === | === General naming functions === | ||
Line 122: | Line 121: | ||
=== Function names === | === Function names === | ||
For most public functions we are limited by Matlab compatibility. Use whatever name Matlab | For most public functions we are limited by Matlab compatibility. Use | ||
whatever name Matlab choose. | |||
There are exceptions to this: | For functions that are not present in Matlab favour 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 138: | 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, 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 with 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. |