mirror of
https://git.osgeo.org/gitea/postgis/postgis
synced 2024-10-23 16:42:35 +00:00
84 lines
2.3 KiB
Plaintext
84 lines
2.3 KiB
Plaintext
Coding Style Guidelines for PostGIS
|
|
-----------------------------------
|
|
|
|
:Preamble:
|
|
|
|
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
|
|
recognize this, and understand it will be the work of many years before
|
|
PostGIS has a consistently named internal set of functions, but,
|
|
we can dream.
|
|
|
|
If new functions follow this guideline, if we do a little rennovation work
|
|
from time to time, we will eventually get there.
|
|
|
|
|
|
:Formatting:
|
|
|
|
All C code should use an ANSI standard formatting with tabs for block
|
|
indenting. When not block indenting, use spaces. To convert a file
|
|
to the standard format use:
|
|
|
|
astyle --style=ansi --indent=tab
|
|
|
|
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
|
|
d) commit
|
|
e) if you are really finicky run astyle again
|
|
f) commit
|
|
|
|
The idea is to avoid combining style-only commits and commits that change
|
|
logic, so the logic commits are easier to read.
|
|
|
|
Macros should be ALL_UPPERCASE.
|
|
Enumerations should be ALL_UPPERCASE.
|
|
|
|
Comments should be written in C style (/* .... */) and not C++ style (//)
|
|
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
|
|
|
|
/**
|
|
* Does something funny
|
|
*/
|
|
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;
|
|
}
|
|
|
|
|
|
:Naming:
|
|
|
|
For ./liblwgeom:
|
|
|
|
- Files should be named with an lw prefix.
|
|
- Functions should have an lw prefix (lw_get_point).
|
|
- Function names should use underscores, not camel case.
|
|
- Function names should indicate the geometry type of inputs
|
|
if relevant (lwline_split)
|
|
|
|
For ./postgis:
|
|
|
|
- C functions called by the back-end directly (function(PG_FUNCTION_ARGS))
|
|
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)
|
|
|