Octave style guide: Difference between revisions

Jump to navigation Jump to search

Octave style guide (edit)

Revision as of 06:28, 10 June 2020

4,079 bytes added ,  10 June 2020
Add Category:Development.
(import more text from the manual)
(8 intermediate revisions by 4 users not shown)
Line 27: Line 27:
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 65: 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
<pre>
  x = 1 / (1 + y) ^ 2;
</pre>
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
expression. 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>
Octave has several functions that produce error messages according
to the Octave guidelines.  Consider using {{codeline|inputParser}}
and {{codeline|validateattributes}}.


== Naming ==
== Naming ==
Line 90: Line 124:


=== Variable names ===
=== Variable names ===
Avoid reusing the names of other functions as local variable names.  For
example, try to avoid naming local variables {{codeline|abs}},
{{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.
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 116: Line 190:
== ! operator ==
== ! operator ==


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


== Comments ==
== Comments ==
Line 134: Line 207:
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 152: Line 248:
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.
[[Category:Development]]
Retrieved from "https://wiki.octave.org/Special:MobileDiff/9536...13114"

Navigation menu