changeset 21537:1ed8718c4f11

doc: Add more suggestions to Contribution Guidelines. * contrib.txi: Add more suggestions to Contribution Guidelines.
author Rik <rik@octave.org>
date Fri, 25 Mar 2016 13:25:30 -0700
parents ca9c8ef555cb
children eb15bc7c5c0b
files doc/interpreter/contrib.txi
diffstat 1 files changed, 49 insertions(+), 19 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/contrib.txi	Fri Mar 25 17:05:34 2016 -0400
+++ b/doc/interpreter/contrib.txi	Fri Mar 25 13:25:30 2016 -0700
@@ -262,7 +262,7 @@
 
 @example
 @group
-Fix bug for complex input for gradient (bug #34292).
+Fix zip, gzip, bzip2 to allow names with spaces (bug #47232)
 @end group
 @end example
 
@@ -274,9 +274,10 @@
 
 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
-statement blocks.  The recommended indent is 2 spaces.  When calling
-functions, put spaces after commas and before the calling parentheses,
-like this:
+statement blocks.  The 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);
@@ -294,7 +295,9 @@
 
 @noindent
 Here, putting spaces after @code{sin}, @code{cos} would result in a
-parse error.  For an indexing expression, do not put a space after the
+parse error.
+
+For indexing expressions, do @emph{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
@@ -310,6 +313,22 @@
   A([1:i-1;i+1:n], XI(:,2:n-1))
 @end example
 
+When constructing matrices, prefer using the comma rather than the space to
+distinguish between columns.
+
+@example
+  M = [1, 2, 3
+       4, 5, 6];
+@end example
+
+However, if the matrix is large or the indentation makes it clear the comma
+may be dropped.
+
+@example
+  prices = [ 1.01  2.02  3.03
+            44.04 55.05  6.06];
+@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
@@ -341,12 +360,17 @@
 @end group
 @end example
 
+The Octave operator @samp{!} should be used for logical negation, rather than
+@samp{~}.  Comments should begin with the @samp{#} character, rather than
+@samp{%}.
+
 @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:
+your editor so that it converts tabs to spaces.
+
+Format function headers like this:
 
 @example
 @group
@@ -357,16 +381,18 @@
 @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 before the left open parenthesis and after commas,
-for both function definitions and function calls.
+The return type of the function and any modifiers are specified on the first
+line.  The function name on the second line 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 before the left open parenthesis and after
+commas, for both function definitions and function calls.
 
 The 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 @emph{both} the curly braces and the
 body of the statement (so that the body gets indented by @emph{two}
-indents).  Example:
+indents).  This format is known as "GNU style" and is an option for some
+code formatting tools.  Example indenting:
 
 @example
 @group
@@ -402,7 +428,7 @@
 more readable, even if they are not necessary.  Also, do not hesitate to
 put extra braces anywhere if it improves clarity.
 
-Declare variables just before they are needed.  Use local variables of
+Declare variables just before they are needed.  Use variables local to
 blocks---it helps optimization.  Don't write a 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.
@@ -424,11 +450,15 @@
 
 Use Octave's types and classes if possible.  Otherwise, use the 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, minimize
-the number of @code{return} statements---use nested @code{if} statements
-if possible.
+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, minimize the
+number of @code{return} statements, but elimination of all but one
+@code{return} is not required.
+
+When an empty string is required, use @code{""}, rather than creating an empty
+string object with @code{std::string ()}.
 
 @node Other Sources
 @section Other Sources
@@ -439,7 +469,7 @@
 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.
+For C, you should follow all C++ rules that can apply.
 
 If you modify a Fortran file, you should stay within Fortran 77 with
 common extensions like @code{END DO}.  Currently, we want all sources to