
******************
Style Guide
******************

This document contains normative rules for writing GNUnet
code and naming conventions used throughout the project.


Naming conventions
==================

Header files
------------
.. Not sure if "include" and "header" files are synonymous.


For header files, the following suffixes should be used:

============= ======================================
Suffix        Usage
============= ======================================
``_lib``      Libraries without associated processes
``_service``  Libraries using service processes
``_plugin``   Plugin definition
``_protocol`` structs used in network protocol
============= ======================================

There exist a few exceptions to these rules within the codebase:

* ``gnunet_config.h`` and ``gnunet_directories.h`` are automatically
  generated. 
* ``gnunet_common.h``, which defines fundamental routines
* ``platform.h``, first included. 
  .. I have no idea what that means
* ``gettext.h``, an external library.


Binaries
--------

For binary files, the following convention should be used:

=============================== =========================================
Name format                     Usage
=============================== =========================================
``gnunet-service-xxx``          Service processes (with listen sockets)
``gnunet-daemon-xxx``           Daemon processes (without listen sockets)
``gnunet-helper-xxx[-yyy]``     SUID helper for module xxx
``gnunet-yyy``                  End-user command line tools
``libgnunet_plugin_xxx_yyy.so`` Plugin for API xxx
``libgnunetxxx.so``             Library for API xxx
=============================== =========================================

Logging
-------

The convention is to define a macro on a per-file basis to manage logging:

.. code-block:: c

   #define LOG(kind,...)
   [logging_macro] (kind, "[component_name]", __VA_ARGS__)

The table below indicates the substitutions which should be made 
for ``[component_name]`` and ``[logging_macro]``.

======================== ========================================= ===================
Software category        ``[component_name]``                      ``[logging_macro]``
======================== ========================================= ===================
Services and daemons     Directory name in ``GNUNET_log_setup``    ``GNUNET_log``
Command line tools       Full name in ``GNUNET_log_setup``         ``GNUNET_log``
Service access libraries ``[directory_name]``                      ``GNUNET_log_from``
Pure libraries           Library name (without ``lib`` or ``.so``) ``GNUNET_log_from``
Plugins                  ``[directory_name]-[plugin_name]``        ``GNUNET_log_from``
======================== ========================================= ===================

.. todo:: Clear up terminology within the style guide (_lib, _service mapped to appropriate software categories)

.. todo:: Interpret and write configuration style

Symbols
-------

Exported symbols must be prefixed with ``GNUNET_[module_name]_`` and be
defined in ``[module_name].c``. The only exceptions to this rule are 
symbols defined in ``gnunet_common.h``.

Private symbols, including ``struct``\ s and macros, must not be prefixed.
In addition, they must not be exported in a way that linkers could use them
or other libraries might see them via headers. This means that they must
**never** be declared in ``src/include``, and only declared or defined in 
C source files or headers under ``src/[module_name]``.


Tests
-----

Test cases and performance tests should follow the naming conventions 
``test_[module-under-test]_[test_description].c`` and
``perf_[module-under-test]_[test_description].c``, respectively.

In either case, if there is only a single test, ``[test_description]``
may be omitted.


``src`` subdirectories
----------------------

Subdirectories of ``src`` 



Coding style
============
.. todo:: Examples should follow GNU Coding Standards?

This project follows the GNU Coding Standards.

Indentation is done with two spaces per level, never with tabs.
Specific (though incomplete) indentation rules are defined in an ``uncrustify``
configuration file (in ``contrib``) and are enforced by Git hooks.

.. todo:: Link to uncrustify config in contrib.

C99-style struct initialisation is acceptable and generally encouraged.

.. todo:: Clarify whether there are cases where C99-style struct init is discouraged?

As in all good C code, we care about symbol space pollution and thus use 
:code:`static` to limit the scope where possible, even in the compilation 
unit that contains :code:`main`.

Only one variable should be declared per line:

.. code-block:: c

   // bad
   int i,j;
   
   // good
   int i;
   int j;

This helps keep diffs small and forces developers to think precisely about
the type of every variable.

Note that :c:`char *` is different from :c:`const char*` and
:c:`int` is different from :c:`unsigned int` or :c:`uint32_t`.
Each variable type should be chosen with care.

.. code-block:: c
