Tips and Standards
******************

This chapter describes no additional features of Octave.  Instead it gives advice on making effective use of the features described in the previous chapters.

Writing Clean Octave Programs
=============================

Here are some tips for avoiding common errors in writing Octave code intended for widespread use:

  * Since all global variables share the same name space, and all functions share another name space, you should choose a short word to distinguish your program from other Octave programs.  Then take care to begin the names of all global variables, constants, and functions with the chosen prefix.  This helps avoid name conflicts.

     If you write a function that you think ought to be added to Octave under a certain name, such as fiddle_matrix, don't call it by that name in your program.  Call it mylib_fiddle_matrix in your program, and send mail to maintainers@octave.org suggesting that it be added to Octave.  If and when it is, the name can be changed easily enough.

     If one prefix is insufficient, your package may use two or three alternative common prefixes, so long as they make sense.

     Separate the prefix from the rest of the symbol name with an underscore _.  This will be consistent with Octave itself and with most Octave programs.

  * When you encounter an error condition, call the function error (or usage).  The error and usage functions do not return. See Errors.

  * Please put a copyright notice on the file if you give copies to anyone. Use the same lines that appear at the top of the function files distributed with Octave.  If you have not signed papers to assign the copyright to anyone else, then place your name in the copyright notice.

Tips for Making Code Run Faster.
================================

Here are some ways of improving the execution speed of Octave programs.

  * Avoid looping wherever possible.

  * Use iteration rather than recursion whenever possible. Function calls are slow in Octave.

  * Avoid resizing matrices unnecessarily.  When building a single result matrix from a series of calculations, set the size of the result matrix first, then insert values into it.  Write

          result = zeros (big_n, big_m)
          for i = over:and_over
            r1 = ...
            r2 = ...
            result (r1, r2) = new_value ();
          endfor

     instead of

          result = [];
          for i = ever:and_ever
            result = [ result, new_value() ];
          endfor

  * Avoid calling eval or feval whenever possible, because they require Octave to parse input or look up the name of a function in the symbol table.

     If you are using eval as an exception handling mechanism and not because you need to execute some arbitrary text, use the try statement instead.  See The try Statement.

  * If you are calling lots of functions but none of them will need to change during your run, set the variable ignore_function_time_stamp to "all" so that Octave doesn't waste a lot of time checking to see if you have updated your function files.

Tips on Writing Comments
========================

Here are the conventions to follow when writing comments.

#
     Comments that start with a single sharp-sign, #, should all be aligned to the same column on the right of the source code.  Such comments usually explain how the code on the same line does its job.  In the Emacs mode for Octave, the M-; (indent-for-comment) command automatically inserts such a # in the right place, or aligns such a comment if it is already present.

##
     Comments that start with a double sharp-sign, ##, 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.

The indentation commands of the Octave mode in Emacs, such as M-; (indent-for-comment) and TAB (octave-indent-line) automatically indent comments according to these conventions, depending on the number of semicolons.  See Manipulating Comments (The GNU Emacs Manual).

Conventional Headers for Octave Functions
=========================================

Octave has conventions for using special comments in function files to give information such as who wrote them.  This section explains these conventions.

The top of the file should contain a copyright notice, followed by a block of comments that can be used as the help text for the function. Here is an example:

     ## Copyright (C) 1996, 1997, 2007 John W. Eaton
     ##
     ## This file is part of Octave.
     ##
     ## Octave is free software; you can redistribute it and/or
     ## modify it under the terms of the GNU General Public
     ## License as published by the Free Software Foundation;
     ## either version 3 of the License, or (at your option) any
     ## later version.
     ##
     ## Octave is distributed in the hope that it will be useful,
     ## but WITHOUT ANY WARRANTY; without even the implied
     ## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
     ## PURPOSE.  See the GNU General Public License for more
     ## details.
     ##
     ## You should have received a copy of the GNU General Public
     ## License along with Octave; see the file COPYING.  If not,
     ## see <http://www.gnu.org/licenses/>.

     ## usage: [IN, OUT, PID] = popen2 (COMMAND, ARGS)
     ##
     ## Start a subprocess with two-way communication.  COMMAND
     ## specifies the name of the command to start.  ARGS is an
     ## array of strings containing options for COMMAND.  IN and
     ## OUT are the file ids of the input and streams for the
     ## subprocess, and PID is the process id of the subprocess,
     ## or -1 if COMMAND could not be executed.
     ##
     ## Example:
     ##
     ##  [in, out, pid] = popen2 ("sort", "-nr");
     ##  fputs (in, "these\nare\nsome\nstrings\n");
     ##  fclose (in);
     ##  while (ischar (s = fgets (out)))
     ##    fputs (stdout, s);
     ##  endwhile
     ##  fclose (out);

Octave uses the first block of comments in a function file that do not appear to be a copyright notice as the help text for the file.  For Octave to recognize the first comment block as a copyright notice, it must start with the word `Copyright' after stripping the leading comment characters.

After the copyright notice and help text come several header comment lines, each beginning with ## HEADER-NAME:.  For example,

     ## Author: jwe
     ## Keywords: subprocesses input-output
     ## Maintainer: jwe

Here is a table of the conventional possibilities for HEADER-NAME:

Author
     This line states the name and net address of at least the principal author of the library.

          ## Author: John W. Eaton <jwe@bevo.che.wisc.edu>

Maintainer
     This line should contain a single name/address as in the Author line, or an address only, or the string jwe.  If there is no maintainer line, the person(s) in the Author field are presumed to be the maintainers.  The example above is mildly bogus because the maintainer line is redundant.

     The idea behind the Author and Maintainer lines is to make possible a function to ``send mail to the maintainer'' without having to mine the name out by hand.

     Be sure to surround the network address with <...> if you include the person's full name as well as the network address.

Created
     This optional line gives the original creation date of the file.  For historical interest only.

Version
     If you wish to record version numbers for the individual Octave program, put them in this line.

Adapted-By
     In this header line, place the name of the person who adapted the library for installation (to make it fit the style conventions, for example).

Keywords
     This line lists keywords.  Eventually, it will be used by an apropos command to allow people will find your package when they're looking for things by topic area.  To separate the keywords, you can use spaces, commas, or both.

Just about every Octave function ought to have the Author and Keywords header comment lines.  Use the others if they are appropriate.  You can also put in header lines with other header names---they have no standard meanings, so they can't do any harm.

Tips for Documentation Strings
==============================

As noted above, documentation is typically in a commented header block on an Octave function following the copyright statement. The help string shown above is an unformatted string and will be displayed as is by Octave. Here are some tips for the writing of documentation strings.

  * Every command, function, or variable intended for users to know about should have a documentation string.

  * An internal variable or subroutine of an Octave program might as well have a documentation string.

  * The first line of the documentation string should consist of one or two complete sentences that stand on their own as a summary.

     The documentation string can have additional lines that expand on the details of how to use the function or variable.  The additional lines should also be made up of complete sentences.

  * For consistency, phrase the verb in the first sentence of a documentation string as an infinitive with ``to'' omitted.  For instance, use ``Return the frob of A and B.'' in preference to ``Returns the frob of A and B.''  Usually it looks good to do likewise for the rest of the first paragraph.  Subsequent paragraphs usually look better if they have proper subjects.

  * Write documentation strings in the active voice, not the passive, and in the present tense, not the future.  For instance, use ``Return a list containing A and B.'' instead of ``A list containing A and B will be returned.''

  * Avoid using the word ``cause'' (or its equivalents) unnecessarily. Instead of, ``Cause Octave to display text in boldface,'' write just ``Display text in boldface.''

  * Do not start or end a documentation string with whitespace.

  * Format the documentation string so that it fits in an Emacs window on an 80-column screen.  It is a good idea for most lines to be no wider than 60 characters.

     However, rather than simply filling the entire documentation string, you can make it much more readable by choosing line breaks with care. Use blank lines between topics if the documentation string is long.

  * Do not indent subsequent lines of a documentation string so that the text is lined up in the source code with the text of the first line.  This looks nice in the source code, but looks bizarre when users view the documentation.  Remember that the indentation before the starting double-quote is not part of the string!

  * The documentation string for a variable that is a yes-or-no flag should start with words such as ``Nonzero means...'', to make it clear that all nonzero values are equivalent and indicate explicitly what zero and nonzero mean.

  * When a function's documentation string mentions the value of an argument of the function, use the argument name in capital letters as if it were a name for that value.  Thus, the documentation string of the operator / refers to its second argument as DIVISOR, because the actual argument name is divisor.

     Also use all caps for meta-syntactic variables, such as when you show the decomposition of a list or vector into subunits, some of which may vary.

Octave also allows extensive formatting of the help string of functions using Texinfo.  The effect on the online documentation is relatively small, but makes the help string of functions conform to the help of Octave's own functions.  However, the effect on the appearance of printed or online documentation will be greatly improved.

The fundamental building block of Texinfo documentation strings is the Texinfo-macro @deftypefn, which takes three arguments: The class the function is in, its output arguments, and the function's signature.  Typical classes for functions include Function File for standard Octave functions, and Loadable Function for dynamically linked functions.  A skeletal Texinfo documentation string therefore looks like this

     -*- texinfo -*-
     @deftypefn{Function File} {@var{ret} = } fn (...)
     @cindex index term
     Help text in Texinfo format.  Code samples should be marked
     like @code{sample of code} and variables should be marked
     as @var{variable}.
     @seealso{fn2}
     @end deftypefn

This help string must be commented in user functions, or in the help string of the DEFUN_DLD macro for dynamically loadable functions.  The important aspects of the documentation string are

-*- texinfo -*-
     This string signals Octave that the following text is in Texinfo format, and should be the first part of any help string in Texinfo format.

@deftypefn{class} ... @end deftypefn
     The entire help string should be enclosed within the block defined by deftypefn.

@cindex index term
     This generates an index entry, and can be useful when the function is included as part of a larger piece of documentation.  It is ignored within Octave's help viewer.

@var{variable}
     All variables should be marked with this macro.  The markup of variables is then changed appropriately for display.

@code{sample of code}
     All samples of code should be marked with this macro for the same reasons as the @var macro.

@seealso{function2}
     This is a comma separated list of function names that allows cross referencing from one function documentation string to another.

Texinfo format has been designed to generate output for online viewing with text-terminals as well as generating high-quality printed output. To these ends, Texinfo has commands which control the diversion of parts of the document into a particular output processor.  Three formats are of importance: info, html and TeX.  These are selected with

     @ifinfo
     Text area for info only
     @end ifinfo

     @ifhtml
     Text area for html only
     @end ifhtml

     @iftex
     @tex
     text for TeX only
     @end tex
     @end iftex

Note that often TeX output can be used in html documents and so often the @ifhtml blocks are unnecessary. If no specific output processor is chosen, by default, the text goes into all output processors. It is usual to have the above blocks in pairs to allow the same information to be conveyed in all output formats, but with a different markup.

Another important feature of Texinfo that is often used in Octave help strings is the @example environment. An example of its use is

     @example
     @group
     @code{2 * 2}
     @result{} 4
     @end group
     @end example

which produces

     2 * 2
     => 4

The @group block prevents the example from being split across a page boundary, while the @result{} macro produces a right arrow signifying the result of a command.

In many cases a function has multiple means in which it can be called, and the @deftypefnx macro can be used to give alternatives. For example

     -*- texinfo -*-
     @deftypefn{Function File} {@var{a} = } fn (@var{x}, ...)
     @deftypefnx{Function File} {@var{a} = } fn (@var{y}, ...)
     Help text in Texinfo format.
     @end deftypefn

Many complete examples of Texinfo documentation can be taken from the help strings for the Octave functions themselves. A relatively complete example of which is the nchoosek function. The Texinfo documentation string of nchoosek is

     -*- texinfo -*-
     @deftypefn {Function File} {} nchoosek (@var{n}, @var{k})

     Compute the binomial coefficient or all combinations of
     @var{n}. If @var{n} is a scalar then, calculate the
     binomial coefficient of @var{n} and @var{k}, defined as

     @iftex
     @tex
     $$
      {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!}
     $$
     @end tex
     @end iftex
     @ifinfo

     @example
     @group
      /   \
      | n |    n (n-1) (n-2) ... (n-k+1)
      |   |  = -------------------------
      | k |               k!
      \   /
     @end group
     @end example
     @end ifinfo

     If @var{n} is a vector, this generates all combinations
     of the elements of @var{n}, taken @var{k} at a time,
     one row per combination. The resulting @var{c} has size
     @code{[nchoosek (length (@var{n}),@var{k}), @var{k}]}.

     @seealso{bincoeff}
     @end deftypefn

which demonstrates most of the concepts discussed above.