doc/README.CODING_STYLE

   1 Some things are mentioned here to help any potential gnutls coder.
   2 The rules here are not always used, although we try to stick to them.
   3
   4
   5 *** File names:
   6   Files are split to directories according to the subsystem
   7  they belong to. Examples are x509/, minitasn1/, openpgp/,
   8  opencdk/ etc. The files in the root directory are of concern
   9  to the main TLS protocol implementation.
  10
  11
  12 *** Function names:
  13   All the function names use underscore "_", to separate words,
  14  functions like gnutlsDoThat are not used. The function names
  15  usually start with "gnutls_" prefix, and the words that follow
  16  specify the exact part of gnutls that this function refers to.
  17  E.g. "gnutls_x509_crt_get_dn", refers to the X.509
  18  certificate parsing part of gnutls. Currently used prefixes are:
  19  "gnutls_x509_crt_" for the X.509 certificate part
  20  "gnutls_openpgp_key_" for the openpgp key part
  21  "gnutls_session_" for the TLS session part (but this may be omited)
  22  "gnutls_handshake_" for the TLS handshake part
  23  "gnutls_record_" for the TLS record protocol part
  24  "gnutls_alert_" for the TLS alert protocol part
  25  "gnutls_credentials_" for the credentials structures
  26  "gnutls_global_" for the global structures handling
  27  and probably more.
  28
  29  Internal functions -- that are not exported in the API -- should
  30  be prefixed with an underscore. E.g. _gnutls_handshake_begin()
  31
  32  Internal structures should not be exported. Especially pointers to
  33  internal data. Doing so harms future reorganization/rewrite of subsystems.
  34
  35  All exported functions must be listed in libgnutls.map and libgnutls-extra.map
  36  in order to be exported.
  37
  38 *** Constructed types:
  39   The constructed types in gnutls always have the "gnutls_" prefix.
  40  Definitions, value defaults and enumerated values should be in
  41  capitals. E.g. GNUTLS_CIPHER_3DES_CBC
  42
  43  Structures should have the '_st' suffix in their name even
  44  if they are a typedef. One can use the sizeof() on types with
  45  '_st' as suffix.
  46
  47  Other constructed types should have the '_t' suffix. A pointer
  48  to a structure also has the '_t' suffix.
  49
  50 *** Function parameters:
  51   The gnutls functions accept parameters in the order:
  52   1. Input parameters
  53   2. Output parameters
  54
  55   When data and size is expected, a gnutls_datum structure should be
  56   used (or more precisely a pointer to the structure).
  57
  58 *** Callback function parameters:
  59   Callback functions should be avoided, if this is possible.
  60  Callbacks that refer to a TLS session should include the
  61  current session as a parameter, in order for the called function to
  62  be able to retrieve the data associated with the session.
  63  This is not always done though -- see the push/pull callbacks.
  64
  65 *** Return values:
  66   Functions in gnutls return an int type, when possible. In that
  67  case 0 should be returned in case of success, or maybe a positive
  68  value, if some other indication is needed.
  69
  70  A negative value always indicates failure. All the available
  71  error codes are defined in gnutls.h and a description
  72  is available in gnutls_errors.c
  73
  74 *** Indentation style:
  75   In general, use the GNU Coding Standard.  You may indent the source
  76   using GNU indent, e.g. "indent *.c".
  77
  78 *** Guile bindings:
  79
  80  Parts of the Guile bindings, such as types (aka. "SMOBs"), enum values,
  81  constants, are automatically generated.  This is handled by the modules
  82  under `guile/modules/gnutls/build/'; these modules are only used at
  83  build-time and are not installed.
  84
  85  The Scheme variables they generate (e.g., constants, type predicates,
  86  etc.) are exported to user programs through `gnutls.scm' and
  87  `gnutls/extra.scm', both of which are installed.
  88
  89  For instance, when adding/removing/renaming enumerates or constants,
  90  two things must be done:
  91
  92   1. Update the enum list in `build/enums.scm' (currently dependencies
  93      are not tracked, so you have to run "make clean all" in `guile/'
  94      after).
  95
  96   2. Update the export list of `gnutls.scm' (or `extra.scm').
  97
  98  Note that, for constants and enums, "schemefied" names are used, as
  99  noted under the "Guile API Conventions" node of the manual.