Changes between Version 20 and Version 21 of Submitting/C

Timestamp:

Jun 11, 2014, 10:22:24 AM (10 years ago)

Author:

martinl

Comment:

--

Submitting/C

@@ -124 +124 @@
 9.  Use `fprintf()` instead of `printf()`
     
-    For errors and warnings please use the `G_fatal_error()` and
-`G_warning()` functions. General messages for the user should use
-`G_message()` while debug messages should use `G_debug()` whenever
-possible. There are two variants to `G_message()`: `G_verbose_message()`
-which will only display the message if in `--verbose` mode, and
-`G_important_message()` which will always show the message unless
-the module is running in `--quiet` mode. `G_fatal_error()` and
-`G_warning()` will always be displayed regardless of verbosity setting.
-Messages sent to any of these functions will be printed to stderr.
+    For errors and warnings please use the `G_fatal_error()` and `G_warning()` functions. General messages for the user should use `G_message()` while debug messages should use `G_debug()` whenever
+possible. There are two variants to `G_message()`: `G_verbose_message()` which will only display the message if in `--verbose` mode, and `G_important_message()` which will always show the message unless the module is running in `--quiet` mode. `G_fatal_error()` and `G_warning()` will always be displayed regardless of verbosity setting. Messages sent to any of these functions will be printed to stderr.
 
     `G_message()` output is not expected to be sent to pipe or file.
 
-    Always use the gettext macros with `_("")` for user messages,
-example:
+    Always use the gettext macros with `_("")` for user messages, example:
 {{{
       G_fatal_error(_("Vector map <%s> not found"), name); 
 }}}
-    It is suggested to add a comment line before translatable user message
-to give a hint to translators about meaning or use of 
-cumbersome or obscure message. First word in the comment must be GTC
-- GRASS translation comment,
+    It is suggested to add a comment line before translatable user message to give a hint to translators about meaning or use of cumbersome or obscure message. First word in the comment must be GTC - GRASS translation comment,
  
     Example:
@@ -159 +148 @@
 
 
-    Pipe/file data output:
-For data output redirected to pipe or file, please use `fprintf()` and 
-specify the stdout stream as follows:
+    Pipe/file data output: For data output redirected to pipe or file, please use `fprintf()` and specify the stdout stream as follows:
 {{{
       fprintf(stdout, ...);
@@ -169 +156 @@
 }}}
 
-10. Use the GRASS library function `G_asprintf()` instead of the
-standard C functions `asprintf()`, `vsnprintf()` and `snprintf()`. These
-functions are not portable or have other issues.  Example:
+10. Use the GRASS library function `G_asprintf()` instead of the standard C functions `asprintf()`, `vsnprintf()` and `snprintf()`. These functions are not portable or have other issues.  Example:
 {{{
     char *msg;
@@ -182 +167 @@
 
 
-11. Use the following GRASS library functions instead of the standard C
-functions. The reason for this is that the following functions ensure
-good programming practice (e.g. always checking if memory was allocated)
-and/or improves portability. PLEASE refer to the programmers manual
-for the proper use (e.g. determining if any casts are needed for arguments
-or return values) of these library functions. They may perform a task
-slightly different from their corresponding C library function, and thus,
-their use may not be the same.
+11. Use the following GRASS library functions instead of the standard C functions. The reason for this is that the following functions ensure good programming practice (e.g. always checking if memory was allocated)
+and/or improves portability. PLEASE refer to the programmers manual for the proper use (e.g. determining if any casts are needed for arguments or return values) of these library functions. They may perform a task slightly different from their corresponding C library function, and thus, their use may not be the same.
 {{{    
         G_malloc() instead of malloc()
@@ -200 +179 @@
         G_sleep() instead of sleep()
 }}}
-        Could somebody please add others (please verify that they are
-useful and safe first)
+        Could somebody please add others (please verify that they are useful and safe first)
 
 
 12. Use function names which fulfill the official GNU naming convention: http://www.gnu.org/prep/standards/html_node/Names.html#Names
 
-    Instead of naming a function like: `MyNewFunction()` use underscores
-for seperation and lower case letters: `my_new_function()``.
+    Instead of naming a function like: `MyNewFunction()` use underscores for seperation and lower case letters: `my_new_function()``.
 
 
@@ -223 +200 @@
     This is safe comparing to nested `/* comments */`
 
-    Functions in the library must be documented in doxygen style to
-get them into the programmer's manual (generate with `make pdfdocs` or `make htmldocs`).
-See [src:grass/trunk/lib/gis/] for examples.
-
-
-14. PLEASE take the time to add comments throughout your code explaining what
-the code is doing. It will save a HUGE amount of time and frustration for
-other programmers that may have to change your code in the future.
-
-
-15. To promote a consistent coding style, please use the "indent" program
-on all new C modules using the following switches:
+    Functions in the library must be documented in doxygen style to get them into the programmer's manual (generate with `make pdfdocs` or `make htmldocs`). See [src:grass/trunk/lib/gis/] for examples.
+
+
+14. PLEASE take the time to add comments throughout your code explaining what the code is doing. It will save a HUGE amount of time and frustration for other programmers that may have to change your code in the future.
+
+
+15. To promote a consistent coding style, please use the "indent" program on all new C modules using the following switches:
 {{{
      $ indent -bad -bap -bbb -br -bli0 -bls -cli0 -ncs -fc1 -hnl -i4 \
@@ -240 +212 @@
       -npsl -nsc -nsob -saf -sai -saw -sbi0 -ss -ts8 -ut main.c
 }}}
-    Existing code should not be re-indented except in extreme cases, as this
-will make "diff" comparisons with older versions impossible. If indent is 
-needed, do not check in any changes other than the indentation in the same 
-commit! Do add the indent switches and any indent warning messages to the 
-SVN log. Any change or fix mixed in with an indent is very hard to track 
-making it hard for others to follow the change or fix any new bugs.
-For your convenience use the src:grass/trunk/tools/grass_indent.sh script.
+    Existing code should not be re-indented except in extreme cases, as this will make "diff" comparisons with older versions impossible. If indent is needed, do not check in any changes other than the indentation in the same commit! Do add the indent switches and any indent warning messages to the SVN log. Any change or fix mixed in with an indent is very hard to track 
+making it hard for others to follow the change or fix any new bugs. For your convenience use the src:grass/trunk/tools/grass_indent.sh script.
 
 
 16. Platform dependent code:
-    Do not remove `#ifdef __CYGWIN__` and/or `#ifndef __CYGWIN__` lines and 
-their encapsulated lines from source code (one example was that someone
-removed `drand48` definition.)
+    Do not remove `#ifdef __CYGWIN__` and/or `#ifndef __CYGWIN__` lines and their encapsulated lines from source code (one example was that someone removed `drand48` definition.)
 
 
 17. Suggested compiler flags:
-    We suggest to use very strict compiler flags to capture errors
-at the very beginning. Here our list of flags, please use them
-to configure you development version of GRASS:
+    We suggest to use very strict compiler flags to capture errors at the very beginning. Here our list of flags, please use them to configure you development version of GRASS:
 
     GNU/Linux:
@@ -272 +235 @@
 
 
-18. Make sure a new line is at the end of each file and UNIX style newlines
-are used (`\n`).
+18. Make sure a new line is at the end of each file and UNIX style newlines are used (`\n`).
 
 
@@ -301 +263 @@
 
 
-21. Have a function included in your module which writes to the history
-file of the map (e.g. command line, parameters etc.). See e.g.
-[src:grass/raster/r.patch/main.c]
+21. Have a function included in your module which writes to the history file of the map (e.g. command line, parameters etc.). See e.g. source:grass/raster/r.patch/main.c
 
     (the same applies to vector and raster3d modules!)
 
 
-22. Standard parser options: use `G_define_standard_option()` whenever possible
-to define standard module command line options. This will save you time,
-create fewer bugs, and make things easier on the translators.
-See [src:grass/trunklib/gis/parser.c] for details of the function definition.
+22. Standard parser options: use `G_define_standard_option()` whenever possible to define standard module command line options. This will save you time, create fewer bugs, and make things easier on the translators.
+See source:grass/trunklib/gis/parser.c for details of the function definition.
 
 
@@ -323 +281 @@
 
 25. GRASS/Environment variables:
-   If you add a new variable, please follow the naming convention.
-All variables are described in src:grass/trunk/lib/init/variables.html
-
-
-26. Be sure to develop on top of the LATEST GRASS code (which is in our SVN
-repository). You can re-check before submission with `svn diff`:
-
-    Be sure to create unified (`diff -u`) format. "Plain" diffs (the default
-format) are risky, because they will apply without warning to code which
-has been substantially changed; they are also harder to read than unified.
-
-    Such diffs should be made from the top-level directory, e.g.
-`svn diff display/d.vect/main.c`; that way, the diff will
-include the pathname rather than just an ambiguous `main.c`.
+   If you add a new variable, please follow the naming convention. All variables are described in src:grass/trunk/lib/init/variables.html
+
+
+26. Be sure to develop on top of the LATEST GRASS code (which is in our SVN repository). You can re-check before submission with `svn diff`:
+
+    Be sure to create unified (`diff -u`) format. "Plain" diffs (the default format) are risky, because they will apply without warning to code which has been substantially changed; they are also harder to read than unified.
+
+    Such diffs should be made from the top-level directory, e.g. `svn diff display/d.vect/main.c`; that way, the diff will include the pathname rather than just an ambiguous `main.c`.
 
 
@@ -369 +321 @@
     You can easily write specific tests for your modules.
 
-    If your module is part of GRASS and you created some standard test
-cases, please contact the developers to add your tests to the
-default test suite.  This will automatize complex test scenarios
-and assure to find bugs much faster, if changes were made to your
-modules or to the grass library.
-
-    Consider to subscribe to the GRASS Quality Assessment System to
-get immediate notification about the code quality:
+    If your module is part of GRASS and you created some standard test cases, please contact the developers to add your tests to the default test suite.  This will automatize complex test scenarios and assure to find bugs much faster, if changes were made to your modules or to the grass library.
+
+    Consider to subscribe to the GRASS Quality Assessment System to get immediate notification about the code quality:
 
     http://lists.osgeo.org/mailman/listinfo/grass-qa
@@ -435 +382 @@
     For your convenience use the src:grass/trunk/tools/module_svn_propset.sh script.
 
-30. Use doxygen style for source code documentation. It is required
-for GRASS libraries, but also recommended for GRASS modules.
-
-    Do not use structural command inside documentation block since it
-leads to some duplication of information (e.g. do not use `\fn`
-command in comment blocks). The exception is `\file` command for
-documenting a file, in this case structural command is required.
+30. Use doxygen style for source code documentation. It is required for GRASS libraries, but also recommended for GRASS modules.
+
+    Do not use structural command inside documentation block since it leads to some duplication of information (e.g. do not use `\fn` command in comment blocks). The exception is `\file` command for documenting a file, in this case structural command is required.
 
     For files
@@ -476 +419 @@
 }}}
 
-31. If you need to add support for a different library in the 'configure' script,
-you should first seek consent in the grass-dev mailing list (see below), then
-you need to expand 'configure.in' and run subsequently `autoconf-2.13` (later
-versions will not work) to re-generate 'configure'.
+31. If you need to add support for a different library in the 'configure' script, you should first seek consent in the grass-dev mailing list (see below), then you need to expand 'configure.in' and run subsequently `autoconf-2.13` (later versions will not work) to re-generate 'configure'.
 
 32. Tell the other developers about the new code using the following e-mail: