# HG changeset patch # User Rik # Date 1464886229 25200 # Node ID adf3473323a74485a5cb5f65c88943872ccba0ca # Parent bc266f3134d7912273dee9d318ee676393a8de3c doc: Add more info about Octave coding conventions. * contrib.txi, tips.txi: Add more info about Octave coding conventions. diff -r bc266f3134d7 -r adf3473323a7 doc/interpreter/contrib.txi --- a/doc/interpreter/contrib.txi Thu Jun 02 09:06:43 2016 -0700 +++ b/doc/interpreter/contrib.txi Thu Jun 02 09:50:29 2016 -0700 @@ -297,7 +297,7 @@ Here, putting spaces after @code{sin}, @code{cos} would result in a parse error. -For indexing expressions, do @emph{not} put a space after the +For indexing expressions, do @strong{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 @@ -337,8 +337,8 @@ Always use a specific end-of-block statement (like @code{endif}, @code{endswitch}) rather than the generic @code{end}. -Enclose the @code{if}, @code{while}, @code{until}, and @code{switch} -conditions in parentheses, as in C: +Enclose the condition of an @code{if}, @code{while}, @code{until}, or +@code{switch} statement in parentheses, as in C: @example @group @@ -349,8 +349,8 @@ @end example @noindent -Do not do this, however, with the iteration counter portion of a -@code{for} statement. Write: +Do not do this, however, with the iteration counter portion of a @code{for} +statement. Write: @example @group @@ -362,11 +362,14 @@ The Octave operator @samp{!} should be used for logical negation, rather than @samp{~}. The negation operator is written with a space between the operator -and its target, e.g., @code{! A}. Comments should begin with the @samp{#} -character, rather than @samp{%}. +and its target, e.g., @code{! A}. -Any Built-In Self Tests or demos using the @code{%!test} or @code{%!demo} -syntax should begin two lines after the @code{endfunction} keyword. +Comments should begin with the @samp{#} character, rather than @samp{%}. +@xref{Comment Tips}. + +Any demos or Built-In Self Tests (BIST) using the @code{%!demo} or +@code{%!test} syntax should begin two lines after the @code{endfunction} +keyword. Demo blocks should be listed before test blocks. @node C++ Sources @section C++ Sources diff -r bc266f3134d7 -r adf3473323a7 doc/interpreter/tips.txi --- a/doc/interpreter/tips.txi Thu Jun 02 09:06:43 2016 -0700 +++ b/doc/interpreter/tips.txi Thu Jun 02 09:50:29 2016 -0700 @@ -63,9 +63,13 @@ @item When you encounter an error condition, call the function @code{error} -(or @code{usage}). The @code{error} and @code{usage} functions do not -return. -@xref{Errors}. +(or @code{print_usage}). The @code{error} and @code{print_usage} functions +do not return. @xref{Errors}. It is customary to prefix the error message +with the name of the function that generated it. For example, + +@example +error ("my_cool_function: input A must be a matrix"); +@end example @item Please put a copyright notice on the file if you give copies to anyone. @@ -82,18 +86,32 @@ @table @samp @item # -Comments that start with a single sharp-sign, @samp{#}, 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 +Comments that start with a single sharp-sign, @samp{#}, are used to explain +the code on the same line as the comment itself. These comments should +all be aligned to the same column to the right of the source code. In the Emacs mode for Octave, the @kbd{M-;} (@code{indent-for-comment}) command automatically inserts such a @samp{#} in the right place, or -aligns such a comment if it is already present. +aligns such a comment if it is already present. Example: + +@example +@var{C} = 2 * pi * r; # formula for circumference of a circle +@end example @item ## -Comments that start with a double sharp-sign, @samp{##}, should be aligned to +Comments that start with a double sharp-sign, @samp{##}, are stand-alone +comments that occupy an entire line. These comments 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. +at that point. Example: + +@example +@group +## Calculate area and volume of a sphere +@var{A} = 4 * pi * r^2; +@var{V} = 4/3 * pi * r^3; +@end group +@end example + @end table @noindent