Changes between Version 44 and Version 45 of Submitting/C


Ignore:
Timestamp:
06/21/14 05:08:29 (11 years ago)
Author:
martinl
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Submitting/C

    v44 v45  
    1 ''Please improve this list...''
    2 
    3 Dear (new) GRASS developer,
    4 
    5 when submitting C code to GRASS SVN repository, please take care of
     1[[TOC]]
     2= Submitting C code =
     3
     4When submitting C code to GRASS SVN repository, please take care of
    65following rules:
    76
    8  * see also [wiki:Submitting/Python Python code hints]
    9  * see also [wiki:Submitting/WxGUI  wxPython GUI code hints]
    10  * see also [wiki:Submitting/Docs documentation hints]
    11  * see also [wiki:Submitting/TclTk Tcl/Tk code hints] (GRASS 6 only)
    12 
    13 1.  Get and read the GRASS Programmer's Manual here:[[BR]]
     7== API Manual ==
     8
     9Get and read the GRASS Programmer's Manual here:[[BR]]
    1410    http://grass.osgeo.org/programming7/
    1511
    16  Or generate it from this source code (the programmer's manual is integrated in the source code in doxygen style):
     12Or generate it from this source code (the programmer's manual is integrated in the source code in doxygen style):
    1713{{{
    1814      make htmldocs
    … …  
    2016}}}
    2117
    22 2.  Use the directory structure to place your module appropriately into the source tree
     18== Directory Conventions ==
     19
     20Use the directory structure to place your module appropriately into the source tree
    2321
    2422        * libraries go into `lib/`
    … …  
    2927    Consider to take a look at "GNU Coding Standards": http://www.gnu.org/prep/standards.html
    3028
    31 
    32 3.  Add a header section to each file you submit and make sure you
     29== Headers ==
     30
     31Add a header section to each file you submit and make sure you
    3332include the copyright. The purpose section is meant to contain a
    3433general overview of the code in the file to assist other
    … …  
    5857    License (http://www.gnu.org).
    5958
    60 
    61 5.  To ensure that the software system continues to work, please include
     59=== GRASS Config Header ===
     60
     61To ensure that the software system continues to work, please include
    6262{{{
    6363        #include <grass/config.h>
    … …  
    6565    in your files and make use of the various system dependencies contained therein.  As one example of this, see source:grass/trunk/lib/gmath/fft.c. Please refrain from declaring system functions within the software; include the proper header files (conditionally dependent on `config.h` macros if necessary) instead.
    6666
    67 
    68 6. Order of include headers
     67=== Other Headers ===
     68
     69Order of include headers
    6970
    7071    In general, headers should be included in the order:
    … …  
    7778    Each class of header has an obligation to be compatible with those above it in the list, but not those below it.
    7879
    79 
    80 7.  Always specify the return type for ALL functions including those that
     80== Functions ==
     81
     82=== Void ===
     83
     84Always specify the return type for ALL functions including those that
    8185return type "void", and insert return statements for any function
    8286which returns a value.
    … …  
    104108}}}
    105109
    106 8.  Module exit status is defined as `EXIT_SUCCESS` or `EXIT_FAILURE`
    107 (declared in `stdlib.h`), e.g.
    108 
    109 {{{
    110     {
    111       ...
    112       if (G_parser (argc, argv))
    113           exit (EXIT_FAILURE);
    114 
    115       ...
    116       exit (EXIT_SUCCESS);
    117     }
    118 }}}
    119 
    120 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.
    121 
    122     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.
    123 
    124     `G_message()` output is not expected to be sent to pipe or file.
    125 
    126     Always use the gettext macros with `_("")` for user messages, example:
    127 {{{
    128       G_fatal_error(_("Vector map <%s> not found"), name);
    129 }}}
    130     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,
    131  
    132     Example:
    133 {{{
    134         /* GTC A name of a projection */
    135         G_message(_("State Plane"));
    136 }}}
    137     Any message with a noun in plural form has to pass _n() macro, even if for the English language it is not required!
    138 {{{
    139        G_message(_n("One map", "%d maps", number), number);
    140 }}}   
    141     See source:grass/trunk/locale/README for details.
    142 
    143 
    144     Pipe/file data output: For data output redirected to pipe or file, please use `fprintf()` and specify the stdout stream as follows:
    145 {{{
    146       fprintf(stdout, ...);
    147       fflush(stdout);
    148 
    149       fflush(stdout) /* always required when using fprintf(stdout, ...). */
    150 }}}
    151 
    152 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:
     110=== G_asprintf() ===
     111
     112Use 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:
    153113{{{
    154114    char *msg;
    … …  
    160120    Note that you should free memory when `G_asprintf()` is used.
    161121
    162 
    163 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)
     122=== Memory Allocations ===
     123
     124Use 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)
    164125and/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.
    165126{{{   
    … …  
    175136        Could somebody please add others (please verify that they are useful and safe first)
    176137
    177 
    178 12. Use function names which fulfill the official GNU naming convention: http://www.gnu.org/prep/standards/html_node/Names.html#Names
     138=== Naming Conventions ===
     139
     140Use function names which fulfill the official GNU naming convention: http://www.gnu.org/prep/standards/html_node/Names.html#Names
    179141
    180142    Instead of naming a function like: `MyNewFunction()` use underscores for seperation and lower case letters: `my_new_function()``.
    181143
    182 
    183 13. Don't use the C++ comment style! This confuses several compilers.
     144=== Comments ===
     145
     146Don't use the C++ comment style! This confuses several compilers.
    184147Use instead:
    185148{{{
    … …  
    196159    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 source:grass/trunk/lib/gis/ for examples.
    197160
    198 
    199 15. To promote a consistent coding style, please use the "indent" program on all new C modules using the following switches:
    200 {{{
    201      $ indent -bad -bap -bbb -br -bli0 -bls -cli0 -ncs -fc1 -hnl -i4 \
    202       -nbbo -nbc -nbfda -nbfde -ncdb -ncdw -nce -nfca -npcs -nprs \
    203       -npsl -nsc -nsob -saf -sai -saw -sbi0 -ss -ts8 -ut main.c
    204 }}}
    205     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 source:grass/trunk/tools/grass_indent.sh script.
    206 
    207 
    208 16. Platform dependent code:
    209     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.)
    210 
    211 
    212 17. Suggested compiler flags:
    213     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:
    214 
    215     GNU/Linux:
    216 {{{
    217        MYCFLAGS="-g -Wall -Werror-implicit-function-declaration -fno-common"
    218        MYCXXFLAGS="-g -Wall"
    219        
    220        CFLAGS="$MYCFLAGS" CXXFLAGS="$MYCXXFLAGS" ./configure ...
    221 }}}
    222     MacOSX:     [to be suggested]
    223 
    224     MS-Windows: [to be suggested]
    225 
    226 
    227 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/trunk/raster/r.patch/main.c (the same applies to vector and raster3d modules!)
    228 
    229 
    230 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.
    231 See source:grass/trunk/lib/gis/parser_standard_options.c for details of the function definition.
    232 
    233 
    234 23. Add/update, if required the related GUI menus:
    235 {{{
    236      gui/wxpython/xml/menudata.xml
    237 }}}
    238 
    239 
    240 30. Use doxygen style for source code documentation. It is required for GRASS libraries, but also recommended for GRASS modules.
     161=== Documentation in Doxygen ===
     162
     163Use doxygen style for source code documentation. It is required for GRASS libraries, but also recommended for GRASS modules.
    241164
    242165    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.
    … …  
    275198}}}
    276199
    277 ...
    278 
    279 ''[please add further hints if required]'''
    280 
    281 ''Your attention to detail is appreciated.''
     200== Modules ==
     201
     202=== Returning Value Of Main function ===
     203
     204Module exit status is defined as `EXIT_SUCCESS` or `EXIT_FAILURE`
     205(declared in `stdlib.h`), e.g.
     206
     207{{{
     208    {
     209      ...
     210      if (G_parser (argc, argv))
     211          exit (EXIT_FAILURE);
     212
     213      ...
     214      exit (EXIT_SUCCESS);
     215    }
     216}}}
     217
     218=== Messages ===
     219
     220Use `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.
     221
     222    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.
     223
     224    `G_message()` output is not expected to be sent to pipe or file.
     225
     226    Always use the gettext macros with `_("")` for user messages, example:
     227{{{
     228      G_fatal_error(_("Vector map <%s> not found"), name);
     229}}}
     230    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,
     231 
     232    Example:
     233{{{
     234        /* GTC A name of a projection */
     235        G_message(_("State Plane"));
     236}}}
     237    Any message with a noun in plural form has to pass _n() macro, even if for the English language it is not required!
     238{{{
     239       G_message(_n("One map", "%d maps", number), number);
     240}}}   
     241    See source:grass/trunk/locale/README for details.
     242
     243
     244    Pipe/file data output: For data output redirected to pipe or file, please use `fprintf()` and specify the stdout stream as follows:
     245{{{
     246      fprintf(stdout, ...);
     247      fflush(stdout);
     248
     249      fflush(stdout) /* always required when using fprintf(stdout, ...). */
     250}}}
     251
     252=== Map History ===
     253
     254Have 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/trunk/raster/r.patch/main.c (the same applies to vector and raster3d modules!)
     255
     256=== Standardized Options and Flags ===
     257
     258Standard 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.
     259See source:grass/trunk/lib/gis/parser_standard_options.c for details of the function definition.
     260
     261== Indentation ==
     262
     26315. To promote a consistent coding style, please use the "indent" program on all new C modules using the following switches:
     264{{{
     265     $ indent -bad -bap -bbb -br -bli0 -bls -cli0 -ncs -fc1 -hnl -i4 \
     266      -nbbo -nbc -nbfda -nbfde -ncdb -ncdw -nce -nfca -npcs -nprs \
     267      -npsl -nsc -nsob -saf -sai -saw -sbi0 -ss -ts8 -ut main.c
     268}}}
     269    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 source:grass/trunk/tools/grass_indent.sh script.
     270
     271== Compilation ==
     272
     273Platform dependent code:
     274    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.)
     275
     276=== Compiler Flags ===
     277
     278Suggested compiler flags:
     279    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:
     280
     281    GNU/Linux:
     282{{{
     283       MYCFLAGS="-g -Wall -Werror-implicit-function-declaration -fno-common"
     284       MYCXXFLAGS="-g -Wall"
     285       
     286       CFLAGS="$MYCFLAGS" CXXFLAGS="$MYCXXFLAGS" ./configure ...
     287}}}
     288    MacOSX:     [to be suggested]
     289
     290    MS-Windows: [to be suggested]