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 11: | Line 11: | ||
=== Line Length === | === Line Length === | ||
Keep the length of source lines to 79 characters or less, for maximum | |||
readability in the widest range of environments. This is inherited from | |||
the [https://www.gnu.org/prep/standards/standards.html#Formatting GNU Coding Standards]. | |||
=== 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 === | ||
When calling functions, put spaces after commas and before the calling | When calling functions, put spaces after commas and before the calling | ||
Line 39: | Line 38: | ||
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. | ||
For indexing expressions, do ''not'' put a space after the | For indexing expressions, do ''not'' put a space after the | ||
Line 52: | Line 49: | ||
<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> | ||
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 63: | Line 58: | ||
</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 65: | ||
44.04 55.05 6.06]; | 44.04 55.05 6.06]; | ||
</pre> | </pre> | ||
Do include spaces around all binary arithmetic operators, for example | Do include spaces around all binary arithmetic operators, for example | ||
Line 81: | Line 72: | ||
</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 80: | ||
</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 91: | ||
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> | ||
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 111: | ||
=== 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. | |||
For functions that are not present in Matlab | 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}}. | For example, {{codeline|base64_decode}}, {{codeline|common_size}}, or | ||
{{codeline|compare_versions}}. There are exceptions to this: | |||
There are exceptions to this: | |||
; Matching C functions | ; Matching C functions | ||
Line 137: | Line 126: | ||
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, try to avoid naming local variables {{codeline|abs}}, | ||
{{codeline|log}}, or {{codeline|pow}}. These | {{codeline|log}}, or {{codeline|pow}}. These functions may be used in a | ||
later change and may lead to 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 190: | ||
== ! operator == | == ! operator == | ||
The Octave operator {{codeline|!}} should be used for logical negation, rather than | |||
{{codeline|~}}. The negation operator is written with a space between the operator | |||
and its target, e.g., {{codeline|! A}}. | |||
== Comments == | == Comments == | ||
Line 208: | Line 199: | ||
=== # or % === | === # or % === | ||
Always use {{Codeline|#}} to write comments | Always use {{Codeline|#}} to write comments. | ||
Absolutely do not use {{codeline|%#}} or mix {{codeline|%}} and {{codeline|#}} | Absolutely do not use {{codeline|%#}} or mix {{codeline|%}} and {{codeline|#}} | ||
Line 258: | Line 249: | ||
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. | ||