Editing Octave style guide

A lot of GNU Octave is written in the Octave language itself.  This document
details the Octave style used by the GNU Octave project.

Being part of the GNU project, Octave inherits the [https://www.gnu.org/prep/standards/standards.html#Writing-C GNU coding standards].  However, those were written
with C in mind and can't always apply to Octave code.

See also the GNU Octave [[C++ style guide]].

== Formatting ==

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

Use only spaces, and indent 2 spaces at a time.

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

When calling functions, put spaces after commas and before the calling
parentheses, like this:

<pre>x = max (sin (y+3), 2);</pre>

An exception are matrix or cell constructors:

<pre>
[sin(x), cos(x)]
{sin(x), cos(x)}
</pre>

Here, putting spaces after {{codeline|sin}}, {{codeline|cos}} would result in a
parse error.

For indexing expressions, do ''not'' put a space after the
identifier (this differentiates indexing and function calls nicely).
The space after a comma is not necessary if index expressions are simple,
i.e., you may write

<pre>A(:,i,j)</pre>

but

<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
distinguish between columns.

<pre>
  M = [1, 2, 3
       4, 5, 6];
</pre>

However, if the matrix is large or the indentation makes it clear the comma
may be dropped.

<pre>
  prices = [ 1.01  2.02  3.03
            44.04 55.05  6.06];
</pre>

== Naming ==

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

=== Function names ===

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

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
: If the function exists elsewhere with a common name, use it.  For example, {{codeline|dup2}}, {{codeline|waitpid}}, {{codeline|printf}}, {{codeline|argv}}, or {{codeline|getopt}}.
; Matching similar functions
: If there are similarly named functions, consider using same style.  For example, {{codeline|fftconvn}} and {{codeline|histthresh}}, match the naming of {{codeline|fftconv2}} and {{codeline|graythresh}}.

=== Variable names ===

== ending blocks ==

Always use a specific end-of-block statement (like {{codeline|endif}},
{{codeline|endswitch}}) rather than the generic {{codeline|end}}.

Enclose the condition of an {{codeline|if}}, {{codeline|while}}, {{codeline|until}}, or
{{codeline|switch}} statement in parentheses, as in C:

<pre>
if (isvector (a))
  s = sum (a);
endif
</pre>

Do not do this, however, with the iteration counter portion of a {{codeline|for}}
statement.  Write:

<pre>
for i = 1:n
  b(i) = sum (a(:,i));
endfor
</pre>

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

=== # or % ===

Always use {{Codeline|#}} to write comments.

Absolutely do not use {{codeline|%#}} or mix {{codeline|%}} and {{codeline|#}}
in the same file.

=== Block and Inline comment ===

Use a single {{codeline|#}} for inline comments.  Use double {{codeline|##}}
for block comments.

=== Commenting out code ===

Do not comment code out.  If the code is no longer used, remove it.  We use
version control, we can always bring it back.

=== %! for test and demo blocks ===

Any demos or Built-In Self Tests (BIST) using the {{codeline|%!demo}} or
{{codeline|%!test}} syntax should begin two lines after the {{codeline|endfunction}}
keyword.  Demo blocks should be listed before test blocks.

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.