Coding Style in SILC source tree
================================
-This documents describes the coding style and coding conventions used
+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
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 GMP math library that uses its own function naming but we have our
+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.
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 describtion of the functionality of the function
+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
is about helps a lot when you go back to it after six months. Static
functions should be commented as well.
-The commenting of functions in SILC has been made into the source files,
-and not in the header files where the function prototypes reside. Header
-files usually includes structure comments, macro comments and perhaps
-some other relevant commenting but usually not function comments.
-It is also Ok to comment the code inside function when it is needed.
+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.
==================
The code should be clean and good to eye, although the function of it
-must always superseed the appearance. However, it is nice to read code
+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
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.
+ 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, if this really isn't that important but some sort of header should
-be in all source files.
+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 `silcincludes.h', this is
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
==============
You should always use silc_calloc instead of silc_malloc because
silc_calloc automatically zeroes the allocated memory area. This is
-imporant especially with structures because generally we want that all
+important especially with structures because generally we want that all
fields, by default, are zero.
So, instead of doing
memset(ptr, 'F', sizeof(*ptr));
silc_free(ptr);
-Where 'F' indicates free'd memory if you ever check it with debugger.
+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
====================
becomes clear they are a wonderful tool.
+Lists
+=====
+
+SILC has two different list API's. The List API and the Dynamic List API.
+Both are based on the TRQ library. For definitions of List API see
+lib/trq/silclist.h and for Dynamic List API see lib/trq/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. GMP is GPL licensed as well
+The original code in SILC is GPL licensed. MPI is GPL licensed as well
and zlib is with free license as well. 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
projects / silc.git / blobdiff