Go to the first, previous, next, last section, table of contents.


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:

Tips for Making Code Run Faster.

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

Tips for Documentation Strings

Here are some tips for the writing of documentation strings.

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 two semicolons, `##', 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 section `Manipulating Comments' in 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 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 2, 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,
## write to the Free Software Foundation, 59 Temple Place -
## Suite 330, Boston, MA 02111-1307, USA.

## 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 (isstr (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 match the regular expression

^ Copyright (C).*\n\n This file is part of Octave.

or

^ Copyright (C).*\n\n This program is free softwar

(after stripping the leading comment characters). This is a fairly strict requirement, and may be relaxed somewhat in the future.

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.


Go to the first, previous, next, last section, table of contents.