doc/interpreter/contrib.txi

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

@node Contributing Guidelines
@appendix Contributing Guidelines
@cindex coding standards
@cindex Octave development

This chapter is dedicated to those who wish to contribute code to Octave.

@menu 
* How to Contribute::		How you may start contributing code.
* General Guidelines::		Advices applicable to any type of source.
* Octave Sources (m-files)::
* C++ Sources::
* Other Sources::	
@end menu

@node How to Contribute
@section How to Contribute
The mailing list for Octave development discussion and sending contributions is
@email{maintainers@@octave.org}. This concerns the development of Octave core,
i.e. code that goes to Octave directly. You may consider developing and
publishing a package instead; a great place for this is the allied Octave-Forge
project (@url{http://octave.sf.net}). Note that the Octave project is
inherently more conservative and follows narrower rules.

The preferable form of contribution is creating a Mercurial changeset and
sending it via e-mail to the octave-maintainers mailing list. Mercurial is the
SCM system currently used to develop Octave. Other forms of contributions (e.g.
simple diff patches) are also acceptable, but they slow down the review process.
If you want to make more contributions, you should really get familiar with
Mercurial.  A good place to start is 
@url{http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial}.
A simplified contribution sequence could look like this:

@example
hg clone http://www.octave.org/hg/octave
cd octave
# change some sources...
hg commit -m "make Octave the coolest software ever"
hg export ../cool.diff
# send ../cool.diff via email
@end example

@node General Guidelines
@section General Guidelines

All Octave's sources are distributed under the General Public License (GPL).
Currently, Octave uses GPL version 3.  For details about this license, see
@url{http://www.gnu.org/licenses/gpl.html}.  Therefore, whenever you create a
new source file, it should have the following comment header (use appropriate
year, name and comment marks):

@example
## Copyright (C) 1996, 1997, 2007 John W. Eaton <jwe@@bevo.che.wisc.edu>
##
## 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/>.
@end example

Always include ChangeLog entries in changesets. After making your source
changes, record and briefly describe the changes in the nearest ChangeLog file
upwards in the directory tree. Use the previous entries as a template. Your
entry should contain your name and email, and the path to the modified source
file relative to the parent directory of the ChangeLog file. If there are more
functions in the file, you should also include the name of the modified function
(in parentheses after file path). Example:

@example
2008-04-02  David Bateman  <dbateman@@free.fr>

        * graphics.cc (void gnuplot_backend::close_figure (const
        octave_value&) const): Allow for an input and output stream.
@end example

@noindent
The ChangeLog entries should describe what is changed, not why.  The reason of
the change should appear in the commit message.

@node Octave Sources (m-files)
@section Octave Sources (m-files)

Don't use tabs. Tabs cause trouble. If you are used to them, set up your editor
so that it converts tabs to spaces.  Indent the bodies of the statement blocks.
Recommended indent is 2 spaces.  When calling functions, put spaces after commas
and before the calling parentheses, like this:

@example
  x = max (sin (y+3), 2);
@end example

@noindent
An exception are matrix and vector constructors:

@example
  [sin(x), cos(x)]
@end example

@noindent
Here, putting spaces after @code{sin}, @code{cos} would result in a parse error.
In indexing expression, do not put a space after the identifier (this
differentiates indexing and function calls nicely). The space after comma is not
necessary if index expressions are simple, i.e. you may write
@example
  A(:,i,j)
@end example

@noindent
but 

@example
  A([1:i-1;i+1:n], XI(:,2:n-1))
@end example

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.

Always use a specific end-of-block statement (like @code{endif},
@code{endswitch}) rather than generic @code{end}. Enclose the @code{if},
@code{while}, @code{until} and @code{switch} conditions in parentheses, 
like in C: 

@example
if (isvector (a))
  s = sum(a);
endif
@end example

@noindent
Do not do this, however, with @code{for}:

@example
for i = 1:n
  b(i) = sum (a(:,i));
endfor
@end example

@node C++ Sources
@section C++ Sources

Don't use tabs. Tabs cause trouble. If you are used to them, set up your editor
so that it converts tabs to spaces. Format function headers like this:

@example
static bool
matches_patterns (const string_vector& patterns, int pat_idx,
		  int num_pat, const std::string& name)
@end example

@noindent
The function name should start in column 1, and multi-line argument lists should
be aligned on the first char after the open parenthesis. You should put a space
after the left open parenthesis and after commas, for both function definitions
and function calls.

Recommended indent is 2 spaces. When indenting, indent the statement after
control structures (like @code{if}, @code{while} etc.). If there is a compound
statement, indent @i{both} the curly braces and the body of the statement (so
that the body gets indented by @i{two} indents). Example:

@example
if (have_args)
  @{
    idx.push_back (first_args);
    have_args = false;
  @}
else
  idx.push_back (make_value_list (*p_args, *p_arg_nm, &tmp));
@end example

@noindent
If you have nested @code{if} statements, use extra braces for extra
clarification. 

Split long expressions in such a way that a continuation line starts with an
operator rather than identifier. If the split occurs inside braces, continuation
should be aligned with the first char after the innermost braces enclosing the
split. Example:

@example
SVD::type type = ((nargout == 0 || nargout == 1)
                  ? SVD::sigma_only
                  : (nargin == 2) ? SVD::economy : SVD::std);
@end example

@noindent
Consider putting extra braces around a multiline expression to make it more
readable, even if they are not necessary.  Also, do not hesitate to put extra
braces anywhere if it improves clarity.

Try declaring variables just before they're needed. Use local variables of
blocks - it helps optimization. Don't write multi-line variable declaration
with a single type specification and multiple variables. If the variables don't
fit on single line, repeat the type specification. Example:

@example
octave_value retval;

octave_idx_type nr = b.rows ();
octave_idx_type nc = b.cols ();

double d1, d2;
@end example

Use lowercase names if possible. Uppercase is acceptable for variable names
consisting of 1-2 letters. Do not use mixed case names.

Try to use Octave's types and classes if possible. Otherwise, try to use C++
standard library. Use of STL containers and algorithms is encouraged.  Use
templates wisely to reduce code duplication. Avoid comma expressions, labels
and gotos, and explicit typecasts. If you need to typecast, use the modern C++
casting operators. In functions, try to reduce the number of @code{return}
statements - use nested @code{if} statements if possible.

@node Other Sources
@section Other Sources
Apart from C++ and Octave language (m-files), Octave's sources include files
written in C, Fortran, M4, perl, unix shell, AWK, texinfo and TeX. There are
not many rules to follow when using these other languages; some of them are
summarized below.  In any case, the golden rule is: if you modify a source
file, try to follow any conventions you can detect in the file or other similar
files.

For C you should obviously follow all C++ rules that can apply.

If you happen to modify a Fortran file, you should stay within Fortran 77
with common extensions like @code{END DO}. Currently, we want all sources
to be compilable with the f2c and g77 compilers, without special flags if
possible. This usually means that non-legacy compilers also accept the sources.

The M4 macro language is mainly used for autoconf configuration files. You should
follow normal M4 rules when contributing to these files. Some M4 files come
from external source, namely the Autoconf archive @url{http://autoconf-archive.cryp.to}.