# HG changeset patch # User Rik # Date 1458937530 25200 # Node ID 1ed8718c4f11d01c7c871df9e2f0d1c640091eb8 # Parent ca9c8ef555cba17547a8ca402b4059a644a7a8f1 doc: Add more suggestions to Contribution Guidelines. * contrib.txi: Add more suggestions to Contribution Guidelines. diff -r ca9c8ef555cb -r 1ed8718c4f11 doc/interpreter/contrib.txi --- 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