Merge commit 'origin/silc.1.1.branch'

[silc.git] / doc / CodingStyle

Coding Style in SILC source tree
================================

This document describes the coding style and coding conventions used
in the SILC source tree.  The purpose of the document is to describe the
common way to program for SILC and thus should be learned when programming
new code.  The document describes various conventions regarding variable
naming, function naming, indentation, overall appearance of a piece of
code and how some of the technical issues has been done in the SILC and
should be done in the future.


Naming
======

Generic naming

All identifiers, whether they are defines, functions or something else, with
exception of variables, has a common naming convention.  Usually all
identifiers use `silc' prefix to indicate that the identifier is part of
SILC distribution.  For example, silc_server_init(), SILC_PACKET_TYPE_ERROR,
etc.  As mentioned however, variables, local or global, does not use this
naming convention.

Lower level routines, usually some library routines, may use their
own naming convention if generic API is defined over them.  The API uses
the common naming convention while the lower level routines uses what
ever they want.  For example, ciphers are implemented currently in this
way.  They define common SILC Cipher API but the actual implementation
of algorithms uses their own naming convention.  Another example is
the MPI math library that uses its own function naming but we have our
own SILC MP API over it that has been defined using common SILC naming
convention.


Variables

Variable names are always in lowercase and any mixed-case or totally
uppercase variable names should be avoided.  Variable names may include
underscore if it is necessary.  For example, `unsigned char *id_string;'.

The same name convention is used in structure field names.  All fields
in structures should be in lowercase.  Global variables should have some
sort of prefix to indicate that the variable is global.  Although, global
variables should be avoided if possible.

Local variable names should be as short as possible without losing
meaning of the name.  For example there is no reason to call loop
counter as `loop_counter' when `i' is commonly used instead.  Using
variable name `tmp' is also ok and should be used when some temporary
value is used.


#define's and Macros

All #define's should always be in uppercase to indicate that it is
a define, for example, `#define SILC_PACKET_TYPE_NONE 0'.  As mentioned
previously #define's and macros always use the `SILC' prefix.  The
names also uses always underscores.

Names of #define's and macros should be self explanatory.  This may
lead to long names but it is better than having some `#define SILC_KE1_SX'
which does not tell you anything.


Type definitions

Type definitions (typedefs) uses some what different naming convention
from variables and macros.  Typedefs has mixed-case names and they
never use underscores.  For example, `SilcSomeStruct', `SilcServerObject'.
Like in any other case the names should be self explanatory which may
lead to long names but that is not a problem.

The names should tell what the typedef is about.  If it is a typedef
of a structure it should tell what the structure is for in the first
place.  For example `SilcClientStruct', `SilcCipherObject', 
`SilcConfigSection´, etc.


Structures

Same naming convention used in typedefs applies to names of structures as
well.  Same as with typedef, structure names should be self explanatory
and should tell what the structure is made for.

Structures are used a lot in SILC.  They are used as simple structures
and as objects as well.  When normal structures are needed they are
defined as follows,

        struct SilcDummyStruct {
          unsigned char *dummy;
        };

And used as `struct SilcDummyStruct *dummy'.  However, this is quite
rarely used in the SILC, instead structures are typedef'd as following
later.  When structure is used as object they are defined as follows,

        typedef struct SilcDummyObject {
          unsigned char *dummy;
          unsigned int flags;
          void (*callback)(void *, unsigned int);
        } SilcDummyStruct;

If the SilcDummyObject is not needed it may be omitted (which is very
common in SILC code), leaving,

        typedef struct {
          unsigned char *dummy;
          unsigned int flags;
          void (*callback)(void *, unsigned int);
        } SilcDummyStruct;

Finally, it is common that structures are typedef'd pointers as they
are very flexible to use,

        typedef SilcDummyStruct *SilcDummy;

or,

        typedef struct {
          unsigned char *dummy;
          unsigned int flags;
          void (*callback)(void *, unsigned int);
        } SilcDummyStruct, *SilcDummy;

It is common in SILC to typedef structures instead of defining name
for the structure.  In this case the structure may be used without
defining `struct' to the code, For example,

        SilcDummyStruct dummy_obj;
        SilcDummyStruct *dummy;

If the structure has a pointer typedef then they are defined as normal
variables but for real they are pointers, For example,

        SilcDummy dummy;
        dummy = silc_calloc(1, sizeof(*dummy));
        dummy->flags = SILC_DUMMY_EMPTY;

This convention is very common in SILC code and has been used consistently
throughout the code.  The pattern here is that all structures are named
as `SilcXxxStruct', all objects are named as `SilcXxxObject' and when
they are typedef'd pointers they are named as `SilcXxx'.


Functions

Function naming uses the common naming convention used in the SILC.  All
functions are always lowercase and they use underscores.  The name of
the function always starts with prefix `silc_'.  The name of the function
should be self explanatory which may lead to long names.  The name of
a function is constructed from following parts,

        silc_<application>_<module>_<function>

The <application> is for example <client> or <server>, however, it is
always omitted (and must be omitted) when programming library code.

The <module> is the module you are programming currently.  You should
have a pretty good idea what you are programming and what the module
does.  For example, <cipher>, <config>, <command>, <packet>, etc.

The <function> is the description of the functionality of the function
you are writing.  Naturally it should be self explanatory and weird
short names should be avoided.  It is better to have long function
names than some odd name that does not tell what it is about.  Function
naming could be for example, <read>, <new_id>, <register>, <find_by_name>,
etc.

So, it is common in SILC to have function names, such as,

        silc_server_packet_send
        silc_server_packet_send_to_channel
        silc_client_packet_process
        silc_idcache_del_by_id
        silc_task_unregister_by_fd
        silc_protocol_excute_final
        silc_buffer_alloc

When function registers something the name of the function should
generally be `silc_function_register' and unregistering should happen
with `silc_function_unregister'.  When function allocates something it
should be called `silc_function_alloc' and when freeing it should be
called `silc_function_free'.  Respectively, with init/uninit functions.

When this naming convention is used consistently it is easy to remember
what the name of the function is.  For example, if you need buffer it
is easy to figure out that the routines are most likely called
`silc_buffer_*',  and if you need to allocate buffer it is most likely
called `silc_buffer_alloc'.  This sort of naming makes the programming,
in the long run, much cleaner, simpler and faster.


Inline functions

SILC uses quite a bit inline functions to optimize the code.  The
naming of inline functions must follow same convention as any normal
function.  All inline functions in SILC are defined and written into
header files.  Inline functions must be defined in following manner
in the header file,

static inline void silc_dummy_inline(unsigned int flags)
{
  doing_little_dummy_things;
}


Indentation
===========

SILC has been coded with Emacs so standard indentation of Emacs is used
in the SILC code.  The indentation is always 2 characters, not a
tabulator.  If you use Emacs then this should not be a problem.  So,
if you code for SILC be sure to format the code to the standard way
used in the SILC before submitting the code.

A tip for those who think that these long function names etc are just
too long to type, consider using dynamic abbreviation found in Emacs.
With this cool feature you only have type some part of the string and
then use the dabbrev to find the rest of the string.  I guess, by
default it is M-/ in Emacs but I have bound it into Shift-TAB so it
is fast to use when typing.


Placing Braces
==============

The common fight about how the braces should be placed in the C code
is probably going on in the SILC code as well.  However, SILC code
is consistent about this.  The placing uses K&R style thus the opening
of the brace is put to the last on the line and the closing brace is
on first on its own line,

        if (condition) {
          silc_something();
          silc_something_more();
        }

The function's braces are as follows,

        int silc_client_function()
        {
          return 0;
        }

More examples,

        if (condition) {
          something;
          silc_something_more();
        } else {
          something_else;
        }

        if (condition) {
          something;
          silc_something_more();
        } else if (other_condition) {
          something;
          silc_something_more();
        } else {
          something_else;
        }

        if (condition)
          oneline_no_braces;


Commenting
==========

SILC code is usually pretty well commented and this should be the way
in the future as well.  However, the comments should not tell how the
code works, it should be apparent by looking at the code.  Instead the
commenting should tell what the function does.  All functions should
be commented.  If nothing more a line of comment telling what the function
is about helps a lot when you go back to it after six months.  Static
functions should be commented as well.

When writing a new header it is preferred that the header file is
immediately written in the ROBOdoc documentation format.  This is
important when you are doing library code under lib/.  There are plenty
of examples of this format.  The ROBOdoc is used automatically generate
the Toolkit documentation.

Comments should use normal C-language comments /* */ and not C++ comments.


General Appearance
==================

The code should be clean and good to eye, although the function of it
must always supersede the appearance.  However, it is nice to read code
that looks good.  Here are some issues on general appearance.

        o Use empty lines when appropriate but not too much.  There
          should not be excess empty lines at the end of file.  However,
          using some empty lines in the code makes the code better
          looking.

        o The line is 79 characters long and not one character longer.
          Longer lines must be cut in two, or three, or ...

        o Use spaces very much.  Do not write things like `if(!k)',
          instead write `if (!k)'.  Same with `for', `while', etc.
          Spaces should be put around all binary operators like `*',
          `==', `+', etc.  Also, when setting a value to variable be
          sure to set spaces around `='.  When writing argument list
          to a function, space should follow each of the comma in the
          list.  However, do not use spaces within parenthesis, for
          example, `if ( !k )' is not accepted.

        o If you are not sure about how something should be done or
          the code you've done is not finished, it should be commented
          with XXX plus explanation what is going on.  For example,
          /* XXX hmm... how is this flushed? */


Source Files

All source files starts with header that includes the name of the author,
copyright notice and the copyright policy, usually part of GNU GPL licence.
Now, this really isn't that important but some sort of header should be in
all source files.

In the start of the source files should include the #include's that are
needed.  All library source files must include `silc.h', this is
a must.  Client source file must include at least `silcclient.h' and
server source file must include `silcserver.h'.  Additional include's
may be added as well, however, system specific includes should not be
added directly (unless it is really a special case).  Go see any source
file as an example.


Header Files

As with source files, header files should include same file header at
the start of the file.

Header files are usually divided in three parts in SILC.  At the start
of header files should include all definitions, typedefs, structure
definitions etc.  After definitions should include macros and inline
functions if any of those exist.  After macros should include the
public prototypes of the functions.  Go see any header file as an example.


Using gotos
===========

Gotos are used in the SILC code quite often.  If you know how to use
goto's properly then it is ok to use them for example to optimize the
code.  If you use goto's then use them only to make forward jumps, try
to avoid backward jumps at all cost.  If you don't know how to use goto's
do not use them.


Debug Messages
==============

When writing new code it is recommended that the code produces some sort
of debug messages.  SILC has own debug logging system that must be used
in the generic SILC code.  Few macros exist,

        SILC_LOG_DEBUG
        SILC_LOG_HEXDUMP
        SILC_LOG_INFO
        SILC_LOG_WARNING
        SILC_LOG_ERROR
        SILC_LOG_FATAL

When doing debugging the most used macros are SILC_LOG_DEBUG and
SILC_LOG_HEXDUMP.  With first macro you can print out any sort of debug
messages with variable argument list, for example,

        SILC_LOG_DEBUG(("Start"));
        SILC_LOG_DEBUG(("Packet length %d", packet_len));

Note the extra parenthesis that are required for the macro so that the
variable argument list formatting would work correctly.

When you need to dump some data into screen you should use SILC_LOG_HEXDUMP
macro.  For example,

        SILC_LOG_HEXDUMP(("Packet"), packet->data, packet->len);
        SILC_LOG_HEXDUMP(("Packet, size %d", size), packet->data, packet->len);

In SILC_LOG_HEXDUMP the data to be dumped are set between the second last
and last parenthesis in order that the data is first and the length of the
data is next.  If arguments are used they are used the same way as in
SILC_LOG_DEBUG and the data to be dumped are set after the argument list
is closed with the parenthesis.


Memory Allocation
=================

Naturally, memory allocation is a big part of SILC.  However, there are
few things that must be noted on the issue.  SILC has defined its own
memory allocation functions that must be used.  System specific functions
must not be used directly.  There are functions like,

        silc_malloc
        silc_calloc
        silc_realloc
        silc_free

You should always use silc_calloc instead of silc_malloc because
silc_calloc automatically zeroes the allocated memory area.  This is
important especially with structures because generally we want that all
fields, by default, are zero.

So, instead of doing

        SilcStruct *ptr;

        ptr = silc_malloc(sizeof(*ptr));

You should do

        SilcStruct *ptr

        ptr = silc_calloc(1, sizeof(*ptr));


When freeing memory it should be zero'ed when appropriate.  All memory
allocations that handle sensitive data such as keys should be zero'ed
by memset() before freeing the memory.  Common way to do is,

        memset(ptr, 'F', sizeof(*ptr));
        silc_free(ptr);

Where 'F' indicates free'd memory if you'd ever check it with debugger.
Other choice is to use 0 instead of 'F'.  The pointer after freeing
should be set to NULL if appropriate, ptr = NULL.

Note that some functions in the SILC library handles the zeroing of
the memory area automatically, like for example, silc_buffer_free.

Also note that all allocation routines assert()'s if the memory allocation
fails, ie. system does not have free memory.


Callback Programming
====================

SILC uses pretty much programming convention called callback programming.
This is a programming style that extensively uses function pointers
which are usually called inside some other function.

Typical scenario is this;  You are performing some task that most likely
is asynchronous.  You need to be able get some structure context when
the operation finishes.  Most common way in this case is to pass the
structure context to the operation function with a callback function
that is called when the operation has finished.  Following code explains
probaly better.


/* Prototypes */
static silc_callback(void *context);
void silc_start();
void silc_async_operation_register(int fd, SilcAsyncCb callback, 
                                   void *context);
void silc_async_operation(int fd, SilcAsyncCb callback, void *context);

/* Type definition of the callback function */
typedef (*SilcAsyncCb)(void *context);

/* Registers async operation and passes callback function and context
   to it as arguments. */

void silc_start()
{
  SilcDummyStruct *ctx;

  ctx = silc_calloc(1, sizeof(*ctx));
  ctx->fd = 30;

  silc_async_operation_register(30, silc_callback, (void *)ctx);
}

/* The callblack function that is called from the operation function */

static void silc_callback(void *context)
{
  SilcDummyStruct *ctx = (SilcDummyStruct *)context;

  ctx->fd = 10;
}

/* Register async operation */

void silc_async_operation_register(int fd, SilcAsyncCb callback,
                                   void *context)
{
  /* Register and return immediately */
  silc_register_async_operation_internal(fd, callback, context);
}

/* Operation function that will call the callback function after it
   has finished. */

void silc_async_operation(int fd, SilcAsyncCb callback, void *context)
{
  here_this_function_does_what_ever_it_wants;

  here_something_more;

  /* We are finished, call the callback */
  if (callback)
    (*callback)(context);
}


Now, after the registeration of the async operation in this dumb example
the silc_start returns immediately.  Lets say, 10 seconds later the
async operation is executed (it would have been better to call it just
timeout) by calling silc_async_operation which on the other hand will
call the callback function after it has finished.  The context that
was passed to the registeration function is now passed back to the
callback function.  Thus, you will get the context you wanted.  This is
the typical scenario where callback functions come in very handy.  This
is also the best way to pass context's that are needed later without
making them global context's.  And as long as the context's are defined
as void * they can be what ever contexts making the functions, that
takes in the context, generic.  Like in above example, you could pass
what ever context to the registeration function if you'd want to.

Callback programming is also used when making generic API's of some
operation.  For example, if you want generic hooks to the API so that
something could be done while doing the operation (maybe to collect
statistics or something else) just get the functions accept a callback
function and context and call them when appropriate, then continue
as normally.

Callback functions has been used a lot in SILC code.  The scheduler
and task system implemented in core library uses extensively callback
functions.  Timeout's uses callbacks as well.  SILC Key Exchange protocol
uses callback functions too.  The callback function in SKE provides
packet sending without defining into the SKE code how the packets
should be sent thus making it generic for both client and server
(and actually to any application for that matter).

There are some technical issues on callback programming that are
common in SILC code.

        o Callback functions are usually defined as void functions
          as the routine that calls them usually don't care about
          what the callback function does.  Many times it doesn't
          actually know what it does nor would it be interested to
          know that.  It doesn't care about return values.

        o Many times the callback functions are static functions
          because they are not wanted to be called in anyway else
          than as callback functions.

        o Callback function names usually have the `_cb' or `_callback'
          at the end of function name, eg. silc_client_cb.

        o Type of callback functions should be typedef'd instead of
          defining them directly to the function.  See above example.
          This makes the code much cleaner.

        o Callback function types has usually the suffix `Cb' or
          ´Callback' in the type name, eg. SilcAsyncCallback.

        o You must explicitly cast the void * context's to correct
          type in the callback function.  Of course you must be careful
          to cast them to the correct type as they are void * they
          could be anything.  Many times this causes problems when you
          forget what was the type you passed to it.  Callback
          programming may get very complex.

        o You cannot use inline functions as callback functions,
          naturally.

Callback programming may be hard to understand from first standing if
you haven't done these before, and debugging them may be pain in the
ass sometimes.  But after the grand idea behind callback functions
becomes clear they are a wonderful tool.


Lists
=====

SILC has two different list API's.  The List API and the Dynamic List API.
For definitions of List API see lib/silcutil/silclist.h and for Dynamic
List API see lib/silcutil/silcdlist.h.  Following short example of the
List API.

List API

typedef struct SilcDummyStruct {
  int dummy;
  void *context;
  struct SilcDummyStruct *next;
} SilcDummy;

int main()
{
  SilcList list;
  SilcDummy *dummy;
  SilcDummy *entry;

  /* Initialize the list */
  silc_list_init(list, struct SilcDummyStruct, next);

  /* Allocate one list entry */
  dummy = silc_calloc(1, sizeof(*dummy));
  dummy->dummy = 100;
  dummy->context = NULL;

  /* Add the entry to the list */
  silc_list_add(list, dummy);

  /* Allocate second list entry */
  dummy = silc_calloc(1, sizeof(*dummy));
  dummy->dummy = 3000;
  dummy->context = NULL;

  /* Add the entry to the list */
  silc_list_add(list, dummy);

  /* Then traverse the list, print the values, remove from list and free
     memory */
  silc_list_start(list);
  while ((entry = silc_list_get(list)) != SILC_LIST_END) {
    fprintf(stderr, "%d\n", entry->dummy);

    /* Remove from list and free memory */
    silc_list_del(list, entry);
    silc_free(entry);
  }

  return 0;
}


Copyrights of the Code
======================

The original code in SILC is GPL licensed.  New code will be accepted to
the official SILC source tree if it is coded in GPL or similiar free
license as GPL is, and of course if it is public domain.  Code with
restricting licenses will not be accepted to the SILC source tree.
SILC is free software, open source, what ever, project and will remain
as such.

Also, about authoring; If you write code to SILC don't forget to add
yourself as author at the start of the file.  The reason for this is
of course that everybody should get the credits they deserve but also
if problems occur we know who to blame. :)