STYLE 2.41 KB
Newer Older
1 2 3 4 5
Coding Style Guidelines for PostGIS
-----------------------------------

:Preamble:

6 7
PostGIS was created over many years, by many different people, some in a
hurry. As a result, the existing coding style is all over the map. We
8
recognize this, and understand it will be the work of many years before
9 10
PostGIS has a consistently named internal set of functions, but,
we can dream.
11 12 13 14 15 16 17

If new functions follow this guideline, if we do a little rennovation work
from time to time, we will eventually get there.


:Formatting:

18
Most C code should use an ANSI standard formatting with tabs for block
19 20 21 22 23
indenting. When not block indenting, use spaces. To convert a file
to the standard format use:

  astyle --style=ansi --indent=tab

24 25 26 27 28
Some files use space indenting instead (check .editorconfig for info).
For them, you can use:

  astyle --style=ansi --indent=spaces=2

29 30 31 32 33 34
Do not get too happy with this command. If you want to re-format a file you
are working on:

 a) run astyle on it
 b) commit
 c) do your work
35 36
 d) run astyle again
 e) commit
37 38 39 40

The idea is to avoid combining style-only commits and commits that change
logic, so the logic commits are easier to read.

41
Macros should be ALL_UPPERCASE.
42 43
Enumerations should be ALL_UPPERCASE.

44
Comments should be written in C style (/* .... */) and not C++ style (//)
45 46 47 48
When describing a function,  the description should be right above the function and should start with /**
This is so the function description can be picked up by the doxygen autodocumentor.  For example

/**
Regina Obe's avatar
Regina Obe committed
49 50
 * Does something funny
 */
51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
double funny_function(POINT2D *p1, POINT2D *p2, POINT2D *q){
	funny stuff here;
}

More advanced commenting
/**
 * Does something funny
 *
 * @param p1       : first point
 * @param p2     : second point
 * @param q   : the quiet point
 *
 * @return a funny double number
 */
double funny_function(POINT2D *p1, POINT2D *p2, POINT2D *q){
	funny stuff here;
}
68

69 70 71

:Naming:

72
For ./liblwgeom:
73 74

- Files should be named with an lw prefix.
75
- Functions should have an lw prefix (lw_get_point).
76 77 78 79
- Function names should use underscores, not camel case.
- Function names should indicate the geometry type of inputs
  if relevant (lwline_split)

80
For ./postgis:
81

82
- C functions called by the back-end directly (function(PG_FUNCTION_ARGS))
83 84 85 86 87
  should be named to match their most likely SQL alias. So
  the SQL ST_Distance(geometry) maps to the C function
  ST_Distance(PG_FUNCTION_ARG)
- C utility functions should be prefixed with pgis_ (lower case)