Editing Octave style guide

Jump to navigation Jump to search
Warning: You are not logged in. Your IP address will be publicly visible if you make any edits. If you log in or create an account, your edits will be attributed to your username, along with other benefits.

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 ===


There is no fixed line length.  In general, strive for clarity and readability and use your own judgement.
Keep the length of source lines to 79 characters or less, for maximum
 
readability in the widest range of environments. This is inherited from
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.
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 '''do not use tabs''' in your code. You should probably set your editor to emit spaces when you hit the tab key.
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 ===
===== 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 37: Line 36:
</pre>
</pre>


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 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>
===== 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 63: Line 58:
</pre>
</pre>


However, if the matrix is large or the indentation makes it clear then the comma
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>
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>
== Error messages ==
When you encounter an error condition, call the function {{codeline|error}}
(or {{codeline|print_usage}}).  The {{codeline|error}} and {{codeline|print_usage}} functions
do not return.
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>
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}}
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 (a.k.a. CamelCase) names.
Use lowercase names if possible.  Uppercase is acceptable for variable
 
names consisting of 1-2 letters.  Do not use mixed case names. Function
Function names must be lowercase.  Function names are global, so choose them wisely.
names must be lowercase.  Function names are global, so choose them
wisely.


=== General naming functions ===
=== General naming functions ===
Line 122: Line 77:
=== Function names ===
=== Function names ===


For most public functions we are limited by Matlab compatibility.  Use whatever name Matlab chose.
For most public functions we are limited by Matlab compatibility.  Use
whatever name Matlab choose.


For functions that are not present in Matlab, favor the use of underscores.
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 135: Line 90:


=== 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 ==
Always use double quotes for strings and characters rather than the Matlab single quote convention. Both quote types are accepted by Octave, but double quoted strings are interpreted slightly differently (see [https://www.gnu.org/software/octave/doc/interpreter/Strings.html Strings] in the manual for details).
'''Do:'''
<pre>
a = "Hello, world";
b = "x";
disp ("This \"string\" contains a\nnewline");
</pre>
'''Don't:'''
<pre>
s = 'Hello, world';
if (x(1) == 'c')
  disp ('Don''t quote one character this way, even if you''re a C programmer');
endif
</pre>
There are a few edge cases where single quoted strings may be preferable, and are permitted as exceptions under this style guide.
; String containing double quotes
: A string that contains many double quote characters itself, where escaping all of them with backslashes becomes inconvenient, may be easier with single quotes.
; String containing backslashes
: A string that contains literal backslashes, in particular a regular expression pattern, where doubly escaping certain character sequences is both inconvenient and harder to read, is usually better done with single quotes.
; Argument interpreted differently
: A string argument to the regexp family of functions may be interpreted differently depending on whether it is a double quoted or single quoted string. Certain escape sequences are interpreted only in a single quoted string for Matlab compatibility.


== ending blocks ==
== ending blocks ==
Line 200: Line 116:
== ! operator ==
== ! operator ==


* The Octave operator <code>!</code> should be used for logical negation, rather than <code>~</code>.
The Octave operator {{codeline|!}} should be used for logical negation, rather than
* The negation operator is written with a space between the operator and its target, e.g., <code>! A</code>.
{{codeline|~}}. The negation operator is written with a space between the operator
* For comparisons use <code>!=</code> instead of <code>~=</code>.
and its target, e.g., {{codeline|! A}}.
 


== Comments ==
== Comments ==
Line 208: Line 125:
=== # or % ===
=== # or % ===


Always use {{Codeline|#}} to write comments for Octave code.  Only use {{Codeline|%}} if code must run in a dual Matlab/Octave environment.
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 217: Line 134:
Use a single {{codeline|#}} for inline comments.  Use double {{codeline|##}}
Use a single {{codeline|#}} for inline comments.  Use double {{codeline|##}}
for block comments.
for block comments.
Comments that start with a single sharp-sign, {{codeline|#}}, are used to explain
the code on the same line as the comment itself.  These comments should
all be aligned to the same column to the right of the source code.  In
the Emacs mode for Octave, the {{codeline|M-;}} (@code{indent-for-comment})
command automatically inserts such a {{codeline|#}} in the right place, or
aligns such a comment if it is already present.  Example:
<pre>
C = 2 * pi * r;    # formula for circumference of a circle
</pre>
Comments that start with a double sharp-sign, {{codeline|##}}, are stand-alone
comments that occupy an entire line.  These comments should be aligned to
the same level of indentation as the code.  Such comments usually
describe the purpose of the following lines or the state of the program
at that point.  Example:
<pre>
## Calculate area and volume of a sphere
A = 4 * pi * r^2;
V = 4/3 * pi * r^3;
</pre>


=== Commenting out code ===
=== Commenting out code ===
Line 253: Line 147:


See the section Writing tests on the [[Tests]] page.
See the section Writing tests on the [[Tests]] page.
=== FIXME notes ===
The preferred comment mark for places that may need further attention is
with {{codeline|FIXME:}} comments.
[[Category:Development]]
Please note that all contributions to Octave may be edited, altered, or removed by other contributors. If you do not want your writing to be edited mercilessly, then do not submit it here.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource (see Octave:Copyrights for details). Do not submit copyrighted work without permission!

To edit this page, please answer the question that appears below (more info):

Cancel Editing help (opens in new window)

Template used on this page:

Retrieved from "https://wiki.octave.org/Octave_style_guide"