Changes between Version 12 and Version 13 of Submitting/C
- Timestamp:
- 06/11/14 09:57:49 (11 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
Submitting/C
v12 v13 59 59 60 60 61 4. We don't want the $ID$in source code any more as it causes problems62 61 4. We don't want the `$ID$` in source code any more as it causes problems 62 for the SVN branches. 63 63 64 64 … … 68 68 }}} 69 69 in your files and make use of the various system dependencies 70 71 72 73 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. 74 74 75 75 … … 84 84 85 85 Each class of header has an obligation to be compatible with those 86 86 above it in the list, but not those below it. 87 87 88 88 89 89 7. Always specify the return type for ALL functions including those that 90 91 90 return type "void", and insert return statements for any function 91 which returns a value. 92 92 93 93 Also, use ANSI C prototypes to declare your functions. 94 94 For module return values, see "Exit status" below. 95 95 96 96 Examples: … … 115 115 116 116 8. Module exit status is defined as `EXIT_SUCCESS` or `EXIT_FAILURE` 117 117 (declared in `stdlib.h`), e.g. 118 118 119 119 {{{ … … 131 131 132 132 For errors and warnings please use the `G_fatal_error()` and 133 134 135 136 137 138 139 140 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. 141 141 142 142 `G_message()` output is not expected to be sent to pipe or file. 143 143 144 144 Always use the gettext macros with `_("")` for user messages, 145 145 example: 146 146 {{{ 147 147 G_fatal_error(_("Vector map <%s> not found"), name); 148 148 }}} 149 149 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: 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 154 Example: 154 155 {{{ 155 156 /* GTC A name of a projection */ … … 157 158 }}} 158 159 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 160 even if for the English language it is not required! 161 {{{ 162 G_message(_n("One map", "%d maps", number), number); 163 }}} 162 164 See [src:grass/trunk/locale/README] for details. 163 165 164 166 165 167 Pipe/file data output: 166 167 168 For data output redirected to pipe or file, please use `fprintf()` and 169 specify the stdout stream as follows: 168 170 {{{ 169 171 fprintf(stdout, ...); … … 174 176 175 177 10. Use the GRASS library function `G_asprintf()` instead of the 176 177 178 standard C functions `asprintf()`, `vsnprintf()` and `snprintf()`. These 179 functions are not portable or have other issues. Example: 178 180 {{{ 179 181 char *msg; … … 187 189 188 190 11. Use the following GRASS library functions instead of the standard C 189 190 191 192 193 194 195 191 functions. The reason for this is that the following functions ensure 192 good programming practice (e.g. always checking if memory was allocated) 193 and/or improves portability. PLEASE refer to the programmers manual 194 for the proper use (e.g. determining if any casts are needed for arguments 195 or return values) of these library functions. They may perform a task 196 slightly different from their corresponding C library function, and thus, 197 their use may not be the same. 196 198 {{{ 197 199 G_malloc() instead of malloc() … … 205 207 }}} 206 208 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 209 useful and safe first) 210 211 212 12. Use function names which fulfill the official GNU naming convention: http://www.gnu.org/prep/standards/html_node/Names.html#Names 212 213 213 214 Instead of naming a function like: `MyNewFunction()` use underscores 214 215 for seperation and lower case letters: `my_new_function()``. 215 216 216 217 217 218 13. Don't use the C++ comment style! This confuses several compilers. 218 219 Use instead: 219 220 {{{ 220 221 /* C-comments */ … … 229 230 230 231 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. 232 get them into the programmer's manual (generate with `make pdfdocs` or `make htmldocs`). 233 See [src:grass/trunk/lib/gis/] for examples. 238 234 239 235 240 236 14. PLEASE take the time to add comments throughout your code explaining what 241 242 237 the code is doing. It will save a HUGE amount of time and frustration for 238 other programmers that may have to change your code in the future. 243 239 244 240 245 241 15. To promote a consistent coding style, please use the "indent" program 246 242 on all new C modules using the following switches: 247 243 {{{ 248 244 $ indent -bad -bap -bbb -br -bli0 -bls -cli0 -ncs -fc1 -hnl -i4 \ … … 251 247 }}} 252 248 Existing code should not be re-indented except in extreme cases, as this 253 254 255 256 257 258 For your convenience use thetools/grass_indent.sh script.249 will make "diff" comparisons with older versions impossible. If indent is 250 needed, do not check in any changes other than the indentation in the same 251 commit! Do add the indent switches and any indent warning messages to the 252 SVN log. Any change or fix mixed in with an indent is very hard to track 253 making it hard for others to follow the change or fix any new bugs. 254 For your convenience use the src:grass/trunk/tools/grass_indent.sh script. 259 255 260 256 261 257 16. Platform dependent code: 262 258 Do not remove `#ifdef __CYGWIN__` and/or `#ifndef __CYGWIN__` lines and 263 264 259 their encapsulated lines from source code (one example was that someone 260 removed `drand48` definition.) 265 261 266 262 267 263 17. Suggested compiler flags: 268 264 We suggest to use very strict compiler flags to capture errors 269 270 265 at the very beginning. Here our list of flags, please use them 266 to configure you development version of GRASS: 271 267 272 268 GNU/Linux: … … 283 279 284 280 18. Make sure a new line is at the end of each file and UNIX style newlines 285 281 are used (`\n`). 286 282 287 283 … … 297 293 cp (normal file) | $(INSTALL) -m 644 file target 298 294 ar | $(AR) 299 300 rm: be VERY careful with recursive remove. Also beware of295 }}} 296 `rm`: be VERY careful with recursive remove. Also beware of 301 297 removing $(FOO)* if $(FOO) has any chance of being empty. 302 298 303 Examples: see below examples or others 304 raster/r.info/Makefile305 vector/v.edit/Makefile306 }}} 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 307 303 If you are unsure, please ask on the GRASS Developers list. 308 304 … … 312 308 313 309 21. Have a function included in your module which writes to the history 314 315 310 file of the map (e.g. command line, parameters etc.). See e.g. 311 [src:grass/raster/r.patch/main.c] 316 312 317 313 (the same applies to vector and raster3d modules!) … … 319 315 320 316 22. Standard parser options: use `G_define_standard_option()` whenever possible 321 322 323 317 to define standard module command line options. This will save you time, 318 create fewer bugs, and make things easier on the translators. 319 See [src:grass/trunklib/gis/parser.c] for details of the function definition. 324 320 325 321 … … 332 328 333 329 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 330 25. GRASS/Environment variables: 331 If you add a new variable, please follow the naming convention. 332 All variables are described in src:grass/trunk/lib/init/variables.html 338 333 339 334 340 335 26. Be sure to develop on top of the LATEST GRASS code (which is in our SVN 341 336 repository). You can re-check before submission with `svn diff`: 342 337 343 338 Be sure to create unified (`diff -u`) format. "Plain" diffs (the default 344 345 339 format) are risky, because they will apply without warning to code which 340 has been substantially changed; they are also harder to read than unified. 346 341 347 342 Such diffs should be made from the top-level directory, e.g. 348 349 343 `svn diff display/d.vect/main.c`; that way, the diff will 344 include the pathname rather than just an ambiguous `main.c`. 350 345 351 346 … … 381 376 382 377 If your module is part of GRASS and you created some standard test 383 384 385 386 378 cases, please contact the developers to add your tests to the 379 default test suite. This will automatize complex test scenarios 380 and assure to find bugs much faster, if changes were made to your 381 modules or to the grass library. 387 382 388 383 Consider to subscribe to the GRASS Quality Assessment System to 389 384 get immediate notification about the code quality: 390 385 391 386 http://lists.osgeo.org/mailman/listinfo/grass-qa … … 417 412 }}} 418 413 To set the svn:ignore property non-interactively, first create a 419 414 file containing the value: 420 415 {{{ 421 416 echo "*.tmp.html" > ignore.txt … … 447 442 448 443 30. Use doxygen style for source code documentation. It is required 449 444 for GRASS libraries, but also recommended for GRASS modules. 450 445 451 446 Do not use structural command inside documentation block since it 452 453 454 447 leads to some duplication of information (e.g. do not use `\fn` 448 command in comment blocks). The exception is `\file` command for 449 documenting a file, in this case structural command is required. 455 450 456 451 For files … … 488 483 489 484 31. If you need to add support for a different library in the 'configure' script, 490 491 492 493 494 32. Tell the other developers about the new code using the following e-mail: [[BR]]485 you should first seek consent in the grass-dev mailing list (see below), then 486 you need to expand 'configure.in' and run subsequently `autoconf-2.13` (later 487 versions will not work) to re-generate 'configure'. 488 489 32. Tell the other developers about the new code using the following e-mail: 495 490 grass-dev@lists.osgeo.org 496 491 497 To subscribe to this mailing list, see [[BR]]492 To subscribe to this mailing list, see 498 493 http://lists.osgeo.org/mailman/listinfo/grass-dev 499 494 … … 504 499 505 500 ... 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.''