1.. _rfc-8: 2 3=========================== 4RFC 8: Developer Guidelines 5=========================== 6 7Author: Frank Warmerdam 8 9Contact: warmerdam@pobox.com 10 11Status: draft 12 13Purpose 14------- 15 16This document is intended to document developer practices for the 17GDAL/OGR project. It will be an evolving document. 18 19Portability 20----------- 21 22GDAL strives to be widely portable to 32bit and 64bit computing 23environments. It accomplishes this in a number of ways - avoid compiler 24specific directives, avoiding new, but perhaps not widely available 25aspects of C++, and most importantly by abstracting platform specific 26operations in CPL functions in the gdal/port directory. 27 28Generally speaking, where available CPL functions should be used in 29preference to operating system functions for operations like memory 30allocation, path parsing, filesystem io, multithreading functions, and 31ODBC access. 32 33Variable Naming 34--------------- 35 36Much of the existing GDAL and OGR code uses an adapted Hungarian naming 37convention. Use of this convention is not mandatory, but when 38maintaining code using this convention it is desirable to continue 39adhering to it with changes. Most importantly, please avoiding using it 40improperly as that can be very confusing. 41 42In Hungarian prefixing the prefix tells something about about the type, 43and potentially semantics of a variable. The following are some prefixes 44used in GDAL/OGR. 45 46- *a*: array 47- *b*: C++ bool. Also used for ints with only TRUE/FALSE values in C. 48- *by*: byte (GByte / unsigned char). 49- *df*: floating point value (double precision) 50- *e*: enumeration 51- *i*: integer number used as a zero based array or loop index. 52- *f*: floating point value (single precision) 53- *h*: an opaque handle (such as GDALDatasetH). 54- *n*: integer number (size unspecified) 55- *o*: C++ object 56- *os*: CPLString 57- *p*: pointer 58- *psz*: pointer to a zero terminated string. (eg. "char \*pszName;") 59- *sz*: zero terminated string (eg." char szName[100];") 60- TODO: What about constants (either global or global to a file)? 61 Propose: *k* 62 63Prefix can be stacked. The following are some examples of meaningful 64variables. 65 66- \*char !\*\ *papszTokens*: Pointer to the an array of strings. 67- \*int *panBands*: Pointer to the first element of an array of 68 numbers. 69- \*double *padfScanline*: Pointer to the first element of an array of 70 doubles. 71- \*double *pdfMeanRet*: Pointer to a single double. 72- \*GDALRasterBand *poBand*: Pointer to a single object. 73- \*GByte *pabyHeader*: Pointer to an array of bytes. 74 75It may also be noted that the standard convention for variable names is 76to capitalize each word in a variable name. 77 78Memory allocation 79----------------- 80 81As per `RFC 19: Safer memory allocation in 82GDAL <./rfc19_safememalloc>`__, you can use VSIMalloc2(x, y) instead of 83doing CPLMalloc(x \* y) or VSIMalloc(x \* y). VSIMalloc2 will detect 84potential overflows in the multiplication and return a NULL pointer if 85it happens. This can be useful in GDAL raster drivers where x and y are 86related to the raster dimensions or raster block sizes. Similarly, 87VSIMalloc3(x, y, z) can be used as a replacement for CPLMalloc(x \* y \* 88z). 89 90Headers, and Comment Blocks 91--------------------------- 92 93.. _misc-notes: 94 95Misc. Notes 96----------- 97 98- Use lower case filenames. 99- Use .cpp extension for C++ files (not .cc). 100- Avoid spaces or other special characters in file or directory names. 101- Use 4 character indentation levels. 102- Use spaces instead of hard tab characters in source code. 103- Try to keep lines to 79 characters or less. 104 105See also 106-------- 107 108- `http://erouault.blogspot.com/2016/01/software-quality-improvements-in-gdal.html <http://erouault.blogspot.com/2016/01/software-quality-improvements-in-gdal.html>`__ 109- `https://travis-ci.org/OSGeo/gdal/builds <https://travis-ci.org/OSGeo/gdal/builds>`__ 110- `https://ci.appveyor.com/project/OSGeo/gdal/history <https://ci.appveyor.com/project/OSGeo/gdal/history>`__ 111- `https://travis-ci.org/rouault/gdal_coverage/builds <https://travis-ci.org/rouault/gdal_coverage/builds>`__ 112- `https://ci.appveyor.com/project/rouault/gdal-coverage/history <https://ci.appveyor.com/project/rouault/gdal-coverage/history>`__ 113- `https://gdalautotest-coverage-results.github.io/coverage_html/index.html <https://gdalautotest-coverage-results.github.io/coverage_html/index.html>`__ 114 115Python code 116----------- 117 118- All Python code in autotest, swig/python/scripts and 119 swig/python/samples should pass OK with the Pyflakes checker (version 120 used currently: 0.8.1). This is asserted by Travis-CI jobs 121- Python code should be written to be compatible with both Python 2 and 122 Python 3. 123