source: branches/samba-3.2.x/docs-xml/Samba3-Developers-Guide/CodingSuggestions.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
<chapter id="CodingSuggestions">
<chapterinfo>
        <author>
                <firstname>Steve</firstname><surname>French</surname>
        </author>
        <author>
                <firstname>Simo</firstname><surname>Sorce</surname>
        </author>
        <author>
                <firstname>Andrew</firstname><surname>Bartlett</surname>
        </author>
        <author>
                <firstname>Tim</firstname><surname>Potter</surname>
        </author>
        <author>
                <firstname>Martin</firstname><surname>Pool</surname>
        </author>
</chapterinfo>

<title>Coding Suggestions</title>

<para>
So you want to add code to Samba ...
</para>

<para>
One of the daunting tasks facing a programmer attempting to write code for
Samba is understanding the various coding conventions used by those most
active in the project.  These conventions were mostly unwritten and helped
improve either the portability, stability or consistency of the code. This
document will attempt to document a few of the more important coding
practices used at this time on the Samba project.  The coding practices are
expected to change slightly over time, and even to grow as more is learned
about obscure portability considerations.  Two existing documents
<filename>samba/source/internals.doc</filename> and 
<filename>samba/source/architecture.doc</filename> provide
additional information.
</para>

<para>
The loosely related question of coding style is very personal and this
document does not attempt to address that subject, except to say that I
have observed that eight character tabs seem to be preferred in Samba
source.  If you are interested in the topic of coding style, two oft-quoted
documents are:
</para>

<para>
<ulink url="http://lxr.linux.no/source/Documentation/CodingStyle">http://lxr.linux.no/source/Documentation/CodingStyle</ulink>
</para>

<para>
<ulink url="http://www.fsf.org/prep/standards_toc.html">http://www.fsf.org/prep/standards_toc.html</ulink>
</para>

<para>
But note that coding style in Samba varies due to the many different
programmers who have contributed.
</para>

<para>
Following are some considerations you should use when adding new code to
Samba.  First and foremost remember that:
</para>

<para>
Portability is a primary consideration in adding function, as is network
compatability with de facto, existing, real world CIFS/SMB implementations.
There are lots of platforms that Samba builds on so use caution when adding
a call to a library function that is not invoked in existing Samba code.
Also note that there are many quite different SMB/CIFS clients that Samba
tries to support, not all of which follow the SNIA CIFS Technical Reference
(or the earlier Microsoft reference documents or the X/Open book on the SMB
Standard) perfectly.
</para>

<para>
Here are some other suggestions:
</para>

<orderedlist>

<listitem><para>
        use d_printf instead of printf for display text
        reason: enable auto-substitution of translated language text 
</para></listitem>

<listitem><para>
        use SAFE_FREE instead of free
        reason: reduce traps due to null pointers
</para></listitem>

<listitem><para>
        don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros
        reason: not POSIX
</para></listitem>

<listitem><para>
        don't use strcpy and strlen (use safe_* equivalents)
        reason: to avoid traps due to buffer overruns
</para></listitem>

<listitem><para>
        don't use getopt_long, use popt functions instead
        reason: portability
</para></listitem>

<listitem><para>
        explicitly add const qualifiers on parm passing in functions where parm
        is input only (somewhat controversial but const can be #defined away)
</para></listitem>

<listitem><para>
        when passing a va_list as an arg, or assigning one to another
        please use the VA_COPY() macro
        reason: on some platforms, va_list is a struct that must be 
        initialized in each function...can SEGV if you don't.
</para></listitem>

<listitem><para>
        discourage use of threads
        reason: portability (also see architecture.doc)
</para></listitem>

<listitem><para>
        don't explicitly include new header files in C files - new h files 
        should be included by adding them once to includes.h
        reason: consistency
</para></listitem>

<listitem><para>
        don't explicitly extern functions (they are autogenerated by 
        "make proto" into proto.h)
        reason: consistency
</para></listitem>

<listitem><para>
        use endian safe macros when unpacking SMBs (see byteorder.h and
        internals.doc)