Changes between Version 12 and Version 13 of Submitting/C


Ignore:
Timestamp:
06/11/14 09:57:49 (10 years ago)
Author:
martinl
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Submitting/C

    v12 v13  
    5959
    6060
    61 4.  We don't want the $ID$ in source code any more as it causes problems
    62     for the SVN branches.
     614.  We don't want the `$ID$` in source code any more as it causes problems
     62for the SVN branches.
    6363
    6464
    … …  
    6868}}}
    6969    in your files and make use of the various system dependencies
    70     contained therein.  As one example of this, see `lib/gmath/fft.c`.
    71     Please refrain from declaring system functions within the
    72     software; include the proper header files (conditionally dependent
    73     on config.h macros if necessary) instead.
     70contained therein.  As one example of this, see `lib/gmath/fft.c`.
     71Please refrain from declaring system functions within the
     72software; include the proper header files (conditionally dependent
     73on config.h macros if necessary) instead.
    7474
    7575
    … …  
    8484 
    8585    Each class of header has an obligation to be compatible with those
    86     above it in the list, but not those below it.
     86above it in the list, but not those below it.
    8787
    8888
    89897.  Always specify the return type for ALL functions including those that
    90     return type "void", and insert return statements for any function
    91     which returns a value.
     90return type "void", and insert return statements for any function
     91which returns a value.
    9292
    9393    Also, use ANSI C prototypes to declare your functions.
    94     For module return values, see "Exit status" below.
     94For module return values, see "Exit status" below.
    9595
    9696    Examples:
    … …  
    115115
    1161168.  Module exit status is defined as `EXIT_SUCCESS` or `EXIT_FAILURE`
    117     (declared in `stdlib.h`), e.g.
     117(declared in `stdlib.h`), e.g.
    118118
    119119{{{
    … …  
    131131   
    132132    For errors and warnings please use the `G_fatal_error()` and
    133     `G_warning()` functions. General messages for the user should use
    134     `G_message()` while debug messages should use `G_debug()` whenever
    135     possible. There are two variants to `G_message()`: `G_verbose_message()`
    136     which will only display the message if in `--verbose` mode, and
    137     `G_important_message()` which will always show the message unless
    138     the module is running in `--quiet` mode. `G_fatal_error()` and
    139     `G_warning()` will always be displayed regardless of verbosity setting.
    140     Messages sent to any of these functions will be printed to stderr.
     133`G_warning()` functions. General messages for the user should use
     134`G_message()` while debug messages should use `G_debug()` whenever
     135possible. There are two variants to `G_message()`: `G_verbose_message()`
     136which will only display the message if in `--verbose` mode, and
     137`G_important_message()` which will always show the message unless
     138the module is running in `--quiet` mode. `G_fatal_error()` and
     139`G_warning()` will always be displayed regardless of verbosity setting.
     140Messages sent to any of these functions will be printed to stderr.
    141141
    142142    `G_message()` output is not expected to be sent to pipe or file.
    143143
    144144    Always use the gettext macros with `_("")` for user messages,
    145     example:
     145example:
    146146{{{
    147147      G_fatal_error(_("Vector map <%s> not found"), name);
    148148}}}
    149149    It is suggested to add a comment line before translatable user message
    150     to give a hint to translators about meaning or use of
    151     cumbersome or obscure message. First word in the comment must be GTC
    152     - GRASS translation comment,
    153     example:
     150to give a hint to translators about meaning or use of
     151cumbersome or obscure message. First word in the comment must be GTC
     152- GRASS translation comment,
     153 
     154    Example:
    154155{{{
    155156        /* GTC A name of a projection */
    … …  
    157158}}}
    158159    Any message with a noun in plural form has to pass _n() macro,
    159     even if for the English language it is not required!
    160         G_message(_n("One map", "%d maps", number), number);
    161        
     160even if for the English language it is not required!
     161{{{
     162       G_message(_n("One map", "%d maps", number), number);
     163}}}   
    162164    See [src:grass/trunk/locale/README] for details.
    163165
    164166
    165167    Pipe/file data output:
    166     For data output redirected to pipe or file, please use `fprintf()` and
    167     specify the stdout stream as follows:
     168For data output redirected to pipe or file, please use `fprintf()` and
     169specify the stdout stream as follows:
    168170{{{
    169171      fprintf(stdout, ...);
    … …  
    174176
    17517710. Use the GRASS library function `G_asprintf()` instead of the
    176     standard C functions `asprintf()`, `vsnprintf()` and `snprintf()`. These
    177     functions are not portable or have other issues.  Example:
     178standard C functions `asprintf()`, `vsnprintf()` and `snprintf()`. These
     179functions are not portable or have other issues.  Example:
    178180{{{
    179181    char *msg;
    … …  
    187189
    18819011. Use the following GRASS library functions instead of the standard C
    189     functions. The reason for this is that the following functions ensure
    190     good programming practice (e.g. always checking if memory was allocated)
    191     and/or improves portability. PLEASE refer to the programmers manual
    192     for the proper use (e.g. determining if any casts are needed for arguments
    193     or return values) of these library functions. They may perform a task
    194     slightly different from their corresponding C library function, and thus,
    195     their use may not be the same.
     191functions. The reason for this is that the following functions ensure
     192good programming practice (e.g. always checking if memory was allocated)
     193and/or improves portability. PLEASE refer to the programmers manual
     194for the proper use (e.g. determining if any casts are needed for arguments
     195or return values) of these library functions. They may perform a task
     196slightly different from their corresponding C library function, and thus,
     197their use may not be the same.
    196198{{{   
    197199        G_malloc() instead of malloc()
    … …  
    205207}}}
    206208        Could somebody please add others (please verify that they are
    207         useful and safe first)
    208 
    209 
    210 12. Use function names which fulfill the official GNU naming convention.[[BR]]
    211     http://www.gnu.org/prep/standards/html_node/Names.html#Names
     209useful and safe first)
     210
     211
     21212. Use function names which fulfill the official GNU naming convention: http://www.gnu.org/prep/standards/html_node/Names.html#Names
    212213
    213214    Instead of naming a function like: `MyNewFunction()` use underscores
    214     for seperation and lower case letters: `my_new_function()``.
     215for seperation and lower case letters: `my_new_function()``.
    215216
    216217
    21721813. Don't use the C++ comment style! This confuses several compilers.
    218     Use instead:
     219Use instead:
    219220{{{
    220221       /* C-comments */
    … …  
    229230
    230231    Functions in the library must be documented in doxygen style to
    231     get them into the programmer's manual (generate with
    232 {{{
    233       make pdfdocs
    234 or
    235       make htmldocs).
    236 }}}
    237     See [src:grass/trunk/lib/gis/] for examples.
     232get them into the programmer's manual (generate with `make pdfdocs` or `make htmldocs`).
     233See [src:grass/trunk/lib/gis/] for examples.
    238234
    239235
    24023614. PLEASE take the time to add comments throughout your code explaining what
    241     the code is doing. It will save a HUGE amount of time and frustration for
    242     other programmers that may have to change your code in the future.
     237the code is doing. It will save a HUGE amount of time and frustration for
     238other programmers that may have to change your code in the future.
    243239
    244240
    24524115. To promote a consistent coding style, please use the "indent" program
    246     on all new C modules using the following switches:
     242on all new C modules using the following switches:
    247243{{{
    248244     $ indent -bad -bap -bbb -br -bli0 -bls -cli0 -ncs -fc1 -hnl -i4 \
    … …  
    251247}}}
    252248    Existing code should not be re-indented except in extreme cases, as this
    253     will make "diff" comparisons with older versions impossible. If indent is
    254     needed, do not check in any changes other than the indentation in the same
    255     commit! Do add the indent switches and any indent warning messages to the
    256     SVN log. Any change or fix mixed in with an indent is very hard to track
    257     making it hard for others to follow the change or fix any new bugs.
    258     For your convenience use the tools/grass_indent.sh script.
     249will make "diff" comparisons with older versions impossible. If indent is
     250needed, do not check in any changes other than the indentation in the same
     251commit! Do add the indent switches and any indent warning messages to the
     252SVN log. Any change or fix mixed in with an indent is very hard to track
     253making it hard for others to follow the change or fix any new bugs.
     254For your convenience use the src:grass/trunk/tools/grass_indent.sh script.
    259255
    260256
    26125716. Platform dependent code:
    262258    Do not remove `#ifdef __CYGWIN__` and/or `#ifndef __CYGWIN__` lines and
    263     their encapsulated lines from source code (one example was that someone
    264     removed `drand48` definition.)
     259their encapsulated lines from source code (one example was that someone
     260removed `drand48` definition.)
    265261
    266262
    26726317. Suggested compiler flags:
    268264    We suggest to use very strict compiler flags to capture errors
    269     at the very beginning. Here our list of flags, please use them
    270     to configure you development version of GRASS:
     265at the very beginning. Here our list of flags, please use them
     266to configure you development version of GRASS:
    271267
    272268    GNU/Linux:
    … …  
    283279
    28428018. Make sure a new line is at the end of each file and UNIX style newlines
    285     are used (`\n`).
     281are used (`\n`).
    286282
    287283
    … …  
    297293    cp  (normal file) | $(INSTALL) -m 644 file target
    298294    ar                | $(AR)
    299 
    300     rm: be VERY careful with recursive remove. Also beware of
     295}}}
     296    `rm`: be VERY careful with recursive remove. Also beware of
    301297    removing $(FOO)* if $(FOO) has any chance of being empty.
    302298
    303     Examples: see below examples or others
    304               raster/r.info/Makefile
    305               vector/v.edit/Makefile
    306 }}}
     299    Examples: see below examples or others[[BR]]
     300              src:grass/trunk/raster/r.info/Makefile[[BR]]
     301              src:grass/trunk/vector/v.edit/Makefile
     302
    307303    If you are unsure, please ask on the GRASS Developers list.
    308304
    … …  
    312308
    31330921. Have a function included in your module which writes to the history
    314     file of the map (e.g. command line, parameters etc.). See e.g.
    315     [src:grass/raster/r.patch/main.c]
     310file of the map (e.g. command line, parameters etc.). See e.g.
     311[src:grass/raster/r.patch/main.c]
    316312
    317313    (the same applies to vector and raster3d modules!)
    … …  
    319315
    32031622. Standard parser options: use `G_define_standard_option()` whenever possible
    321     to define standard module command line options. This will save you time,
    322     create fewer bugs, and make things easier on the translators.
    323     See [src:grass/trunklib/gis/parser.c] for details of the function definition.
     317to define standard module command line options. This will save you time,
     318create fewer bugs, and make things easier on the translators.
     319See [src:grass/trunklib/gis/parser.c] for details of the function definition.
    324320
    325321
    … …  
    332328
    333329
    334 25. GRASS/Environment variables:[[BR]]
    335     If you add a new variable, please follow the naming convention.[[BR]]
    336     All variables are described in[[BR]]
    337     src:grass/trunk/lib/init/variables.html
     33025. GRASS/Environment variables:
     331   If you add a new variable, please follow the naming convention.
     332All variables are described in src:grass/trunk/lib/init/variables.html
    338333
    339334
    34033526. Be sure to develop on top of the LATEST GRASS code (which is in our SVN
    341     repository). You can re-check before submission with `svn diff`:
     336repository). You can re-check before submission with `svn diff`:
    342337
    343338    Be sure to create unified (`diff -u`) format. "Plain" diffs (the default
    344     format) are risky, because they will apply without warning to code which
    345     has been substantially changed; they are also harder to read than unified.
     339format) are risky, because they will apply without warning to code which
     340has been substantially changed; they are also harder to read than unified.
    346341
    347342    Such diffs should be made from the top-level directory, e.g.
    348     `svn diff display/d.vect/main.c`; that way, the diff will
    349     include the pathname rather than just an ambiguous `main.c`.
     343`svn diff display/d.vect/main.c`; that way, the diff will
     344include the pathname rather than just an ambiguous `main.c`.
    350345
    351346
    … …  
    381376
    382377    If your module is part of GRASS and you created some standard test
    383     cases, please contact the developers to add your tests to the
    384     default test suite.  This will automatize complex test scenarios
    385     and assure to find bugs much faster, if changes were made to your
    386     modules or to the grass library.
     378cases, please contact the developers to add your tests to the
     379default test suite.  This will automatize complex test scenarios
     380and assure to find bugs much faster, if changes were made to your
     381modules or to the grass library.
    387382
    388383    Consider to subscribe to the GRASS Quality Assessment System to
    389     get immediate notification about the code quality:
     384get immediate notification about the code quality:
    390385
    391386    http://lists.osgeo.org/mailman/listinfo/grass-qa
    … …  
    417412}}}
    418413    To set the svn:ignore property non-interactively, first create a
    419     file containing the value:
     414file containing the value:
    420415{{{
    421416      echo "*.tmp.html" > ignore.txt
    … …  
    447442
    44844330. Use doxygen style for source code documentation. It is required
    449     for GRASS libraries, but also recommended for GRASS modules.
     444for GRASS libraries, but also recommended for GRASS modules.
    450445
    451446    Do not use structural command inside documentation block since it
    452     leads to some duplication of information (e.g. do not use `\fn`
    453     command in comment blocks). The exception is `\file` command for
    454     documenting a file, in this case structural command is required.
     447leads to some duplication of information (e.g. do not use `\fn`
     448command in comment blocks). The exception is `\file` command for
     449documenting a file, in this case structural command is required.
    455450
    456451    For files
    … …  
    488483
    48948431. If you need to add support for a different library in the 'configure' script,
    490     you should first seek consent in the grass-dev mailing list (see below), then
    491     you need to expand 'configure.in' and run subsequently `autoconf-2.13` (later
    492     versions will not work) to re-generate 'configure'.
    493 
    494 32. Tell the other developers about the new code using the following e-mail:[[BR]]
     485you should first seek consent in the grass-dev mailing list (see below), then
     486you need to expand 'configure.in' and run subsequently `autoconf-2.13` (later
     487versions will not work) to re-generate 'configure'.
     488
     48932. Tell the other developers about the new code using the following e-mail:
    495490    grass-dev@lists.osgeo.org
    496491 
    497     To subscribe to this mailing list, see[[BR]]
     492    To subscribe to this mailing list, see
    498493    http://lists.osgeo.org/mailman/listinfo/grass-dev
    499494
    … …  
    504499
    505500...
    506 [please add further hints if required]
    507 
    508 
    509 "Your attention to detail is appreciated."
     501
     502''[please add further hints if required]'''
     503
     504''Your attention to detail is appreciated.''