[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This chapter describes no additional features of Octave. Instead it gives advice on making effective use of the features described in the previous chapters.
A.1 Writing Clean Octave Programs | Writing clean and robust programs. | |
A.2 Tips for Making Code Run Faster. | Making code run faster. | |
A.3 Tips for Documentation Strings | Writing readable documentation strings. | |
A.4 Tips on Writing Comments | Conventions for writing comments. | |
A.5 Conventional Headers for Octave Functions | Standard headers for functions. |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here are some tips for avoiding common errors in writing Octave code intended for widespread use:
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.
error
(or usage
). The error
and usage
functions do not
return.
See section 2.5 How Octave Reports Errors.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here are some ways of improving the execution speed of Octave programs.
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 |
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 section 12.9 The try
Statement.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here are some tips for the writing of documentation strings.
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.
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.
/
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here are the conventions to follow when writing comments.
indent-for-comment
)
command automatically inserts such a `#' in the right place, or
aligns such a comment if it is already present.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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, Inc., 51 Franklin Street, ## Fifth Floor, Boston, MA 02110-1301, 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: John W. Eaton <jwe@bevo.che.wisc.edu> |
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.
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.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |