Changes between Initial Version and Version 1 of Submitting/C

Timestamp:

Jun 11, 2014, 9:43:44 AM (10 years ago)

Author:

martinl

Comment:

--

Submitting/C

@@ +1 @@
+NOTE: Please improve this list!
+
+Dear (new) GRASS developer,
+
+when submitting C code to GRASS SVN repository, please take care of
+following rules:
+
+ * [wiki:Submitting/Python Python code hints]
+ * [wiki:Submitting/WxGUI for wxPython GUI code hints]
+ * [wiki:Submitting/Docs for documentation]
+
+1.  Get and read the GRASS Programmer's Manual here:[[BR]]
+    http://grass.osgeo.org/programming7/
+
+    or generate it from this source code (the programmer's manual is
+    integrated in the source code in doxygen style):
+{{{
+      make htmldocs
+      make pdfdocs
+}}}
+
+2.  Use the directory structure to place your module appropriately into
+    the source tree
+{{{
+        - libes go into lib/
+        - raster modules go into raster/
+        - vector modules go into vector/
+        - ...
+}}}
+    Consider to take a look at "GNU Coding Standards"[[BR]]
+    http://www.gnu.org/prep/standards.html
+
+
+3.  Add a header section to each file you submit and make sure you
+    include the copyright. The purpose section is meant to contain a
+    general overview of the code in the file to assist other
+    programmers that will need to make changes to your code. If you
+    are modifying an existing file you may under no circumstances
+    remove prior copyright or licensing text that is not your own,
+    even for a major rewrite. If any original code or code that is in
+    part derived from another's original work remains, it must be
+    properly cited.
+
+    Example (ficticious header for a file called color.c) :
+{{{
+/****************************************************************************
+ *
+ * MODULE:       g.foo
+ * AUTHOR(S):    John Doe <jdoe at somewhere org>
+ * PURPOSE:      Provide short description of module here...
+ * COPYRIGHT:    (C) 2010 by John Doe, and the GRASS Development Team
+ *
+ *               This program is free software under the GNU General Public
+ *               License (>=v2). Read the COPYING file that comes with GRASS
+ *               for details.
+ *
+ *****************************************************************************/
+}}}
+    The copyright protects your rights according to GNU General Public
+    License (www.gnu.org).
+
+
+4.  We don't want the $ID$ in source code any more as it causes problems
+    for the SVN branches.
+
+
+5.  To ensure that the software system continues to work, please include
+{{{
+        #include <grass/config.h>
+}}}
+    in your files and make use of the various system dependencies
+    contained therein.  As one example of this, see `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.
+
+
+6. Order of include headers
+
+    In general, headers should be included in the order:
+ 
+    1. Core system headers (stdio.h, ctype.h, ...)
+    2. Headers for non-core system components (X11, libraries).
+    3. Headers for core systems of the package being compiled (`grass/gis.h`, `grass/glocale.h`, ...)
+    4. Headers for the specific library/program being compiled (`geodesic.h`, ...)
+ 
+    Each class of header has an obligation to be compatible with those
+    above it in the list, but not those below it.
+
+
+7.  Always specify the return type for ALL functions including those that
+    return type "void", and insert return statements for any function
+    which returns a value.
+
+    Also, use ANSI C prototypes to declare your functions. 
+    For module return values, see "Exit status" below.
+
+    Examples:
+{{{    
+    void G_something(void);
+    int G_something_else(int, int);
+    
+    void G_something(void)
+    {
+        /* Snipped out code */
+        
+        return;
+    }
+    
+    int G_something_else(int x, int y)
+    {
+        /* Snipped out code */
+        
+        return 0;
+    }
+}}}
+
+8.  Module exit status is defined as `EXIT_SUCCESS` or `EXIT_FAILURE`
+    (declared in `stdlib.h`), e.g.
+
+{{{
+    {
+      ...
+      if (G_parser (argc, argv))
+          exit (EXIT_FAILURE);
+
+      ...
+      exit (EXIT_SUCCESS);
+    }
+}}}
+
+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.
+
+    `G_message()` output is not expected to be sent to pipe or file.
+
+    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,
+    example:
+{{{
+        /* GTC A name of a projection */
+        G_message(_("State Plane"));
+}}} 
+    Any message with a noun in plural form has to pass _n() macro,
+    even if for the English language it is not required!
+        G_message(_n("One map", "%d maps", number), number);
+        
+    See [src:grass/trunk/locale/README] for details.
+
+
+    Pipe/file data output:
+    For data output redirected to pipe or file, please use `fprintf()` and 
+    specify the stdout stream as follows:
+{{{
+      fprintf(stdout, ...);
+      fflush(stdout);
+
+      fflush(stdout) /* always required when using fprintf(stdout, ...). */
+}}}
+
+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;
+
+    G_asprintf(&msg, "%s", parameters);
+    do_something_with_msg();
+    G_free(msg);
+}}}
+    Note that you should free memory when `G_asprintf()` is used.
+
+
+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()
+        G_calloc() instead of calloc()
+        G_realloc() instead of realloc()
+        G_free() instead of free()
+        G_getenv() instead of getenv()
+        G_setenv() instead of setenv()
+        G_unsetenv() instead of unsetenv()
+        G_sleep() instead of sleep()
+}}}
+        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.[[BR]]
+    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()``.
+
+
+13. Don't use the C++ comment style! This confuses several compilers.
+    Use instead:
+{{{
+       /* C-comments */
+}}}
+    If you want to comment code portions, use
+{{{
+       #ifdef notdef 
+            portion_to_be_commented;
+       #endif
+}}}
+    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:
+{{{
+     $ indent -bad -bap -bbb -br -bli0 -bls -cli0 -ncs -fc1 -hnl -i4 \
+      -nbbo -nbc -nbfda -nbfde -ncdb -ncdw -nce -nfca -npcs -nprs \
+      -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 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.)
+
+
+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:
+
+    GNU/Linux:
+{{{
+       MYCFLAGS="-g -Wall -Werror-implicit-function-declaration -fno-common"
+       MYCXXFLAGS="-g -Wall"
+       
+       CFLAGS="$MYCFLAGS" CXXFLAGS="$MYCXXFLAGS" ./configure ... 
+}}}
+    MacOSX:     [to be suggested]
+
+    MS-Windows: [to be suggested]
+
+
+18. Make sure a new line is at the end of each file and UNIX style newlines
+    are used (`\n`).
+
+
+19. When writing Makefiles, use the current standard.
+
+    If you have to use commands, please check for:
+{{{    
+            avoid     | use instead
+    ------------------+---------------
+    make target       | $(MAKE) target
+    mkdir target      | $(MKDIR) target
+    cp  (executable)  | $(INSTALL) -m 755 file target
+    cp  (normal file) | $(INSTALL) -m 644 file target
+    ar                | $(AR)
+
+    rm: be VERY careful with recursive remove. Also beware of
+    removing $(FOO)* if $(FOO) has any chance of being empty.
+
+    Examples: see below examples or others
+              raster/r.info/Makefile
+              vector/v.edit/Makefile
+}}}
+    If you are unsure, please ask on the GRASS Developers list.
+
+    
+20. Have a look at [src:grass/trunk/INSTALL]
+
+
+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]
+
+    (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.
+
+
+23. Add/update, if required the related GUI menus:
+{{{
+     gui/wxpython/xml/menudata.xml
+}}}
+
+24. For consistency, use `README` rather than `README.txt` for any `README` files.
+
+
+25. GRASS/Environment variables:[[BR]]
+    If you add a new variable, please follow the naming convention.[[BR]]
+    All variables are described in[[BR]]
+    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`.
+
+
+27. Try to use module names which describe shortly the intended purpose of the module.
+
+    The first letters for module name should be:
+{{{
+        d.      - display commands
+        db.     - database commands
+        g.      - general GIS management commands
+        i.      - imagery commands
+        m.      - miscellaneous tool commands
+        ps.     - postscript commands
+        r.      - raster commands
+        r3.     - raster3D commands
+        v.      - vector commands
+}}}
+    Some additional naming conventions
+    * export modules:     (type).out.(format) eg: r.out.arc, v.out.ascii
+    * import module:      (type).in.(format)  eg: r.in.arc, v.in.ascii
+    * conversion modules: (type).to.(type)    eg: r.to.vect, v.to.rast, r3.to.rast
+
+    Avoid module names with more than two dots in the name. 
+    Example:
+       instead of r.to.rast3.elev use r.to.rast3elev    
+
+
+28. Use the grass test suite to test your modules.
+
+    http://www-pool.math.tu-berlin.de/~soeren/grass/GRASS_TestSuite
+
+    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:
+
+    http://lists.osgeo.org/mailman/listinfo/grass-qa
+
+
+29. When submitting new files to the repository set SVN properties,
+    usually for directory
+{{{
+      svn:ignore : *.tmp.html
+                   *OBJ*
+}}}
+    or e.g. for C-file
+{{{    
+      svn:mime-type : text/x-csrc
+      svn:keywords : Author Date Id
+      svn:eol-style : native
+}}}
+    See
+    http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+    To set a property:
+{{{
+      svn propset svn:keywords 'Author Date Id' <file>
+      svn propset svn:mime-type text/x-sh grass_shellscript.sh
+}}}
+    To edit the `svn:ignore` property using your default text editor:
+{{{
+      svn propedit svn:ignore <directory>
+}}}
+    To set the svn:ignore property non-interactively, first create a
+    file containing the value:
+{{{
+      echo "*.tmp.html" > ignore.txt
+      echo "*OBJ*" >> ignore.txt
+}}}
+    then use:
+{{{
+      svn propset -F ignore.txt svn:ignore <directory>
+}}}
+    List of mime-type:
+{{{
+      C++ files (.cpp): text/x-c++src
+      C files (.c): text/x-csrc
+      DTD files (.dtd): text/xml-dtd
+      GIF files (.gif): image/gif
+      Header files (.h): text/x-chdr
+      HTML files (.html): text/html
+      JPEG files (.jpg): image/jpeg
+      Makefiles: text/x-makefile
+      PNG files (.png): image/png
+      Python files (.py): text/x-python
+      Shell scripts (.sh): text/x-sh
+      Text files (.txt): text/plain
+      XML files (.xml): text/xml
+}}} 
+      (please update the list...)
+
+    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.
+
+    For files
+{{{
+    /*!
+       \file snap.c
+   
+       \brief Vector library - Clean vector map (snap lines)
+
+       (C) 2001-2008 by the GRASS Development Team
+   
+       This program is free software under the GNU General Public
+       License (>=v2).  Read the file COPYING that comes with GRASS
+       for details.
+   
+       \author Radim Blazek
+    */
+}}}
+    For functions
+{{{
+    /*!
+       \brief Snap lines in vector map to existing vertex in threshold
+
+       For details see Vect_snap_lines_list()
+
+       \param Map pointer to input vector map 
+       \param type filter features of given type to be snap
+       \param thresh threshold value for snapping
+       \param[out] Err pointer to vector map where lines representing snap are written or NULL
+       \param[out] msgout file pointer where messages will be written or NULL
+       
+       \return 1           
+    */
+}}}
+
+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:[[BR]]
+    grass-dev@lists.osgeo.org
+ 
+    To subscribe to this mailing list, see[[BR]]
+    http://lists.osgeo.org/mailman/listinfo/grass-dev
+
+
+33. In case of questions feel free to contact the developers at the above
+    mailing list.[[BR]]
+    http://grass.osgeo.org/development/
+
+...
+[please add further hints if required]
+
+
+"Your attention to detail is appreciated."