| 1 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 6. Coding Suggestions</title><link rel="stylesheet" href="../samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.74.0"><link rel="home" href="index.html" title="SAMBA Developers Guide"><link rel="up" href="pt02.html" title="Part II. Samba Basics"><link rel="prev" href="internals.html" title="Chapter 5. Samba Internals"><link rel="next" href="contributing.html" title="Chapter 7. Contributing code"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 6. Coding Suggestions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="internals.html">Prev</a> </td><th width="60%" align="center">Part II. Samba Basics</th><td width="20%" align="right"> <a accesskey="n" href="contributing.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="CodingSuggestions"></a>Chapter 6. Coding Suggestions</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Steve</span> <span class="surname">French</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Simo</span> <span class="surname">Sorce</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Andrew</span> <span class="surname">Bartlett</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Tim</span> <span class="surname">Potter</span></h3></div></div><div><div class="author"><h3 class="author"><span class="firstname">Martin</span> <span class="surname">Pool</span></h3></div></div></div></div><p>
|
|---|
| 2 | So you want to add code to Samba ...
|
|---|
| 3 | </p><p>
|
|---|
| 4 | One of the daunting tasks facing a programmer attempting to write code for
|
|---|
| 5 | Samba is understanding the various coding conventions used by those most
|
|---|
| 6 | active in the project. These conventions were mostly unwritten and helped
|
|---|
| 7 | improve either the portability, stability or consistency of the code. This
|
|---|
| 8 | document will attempt to document a few of the more important coding
|
|---|
| 9 | practices used at this time on the Samba project. The coding practices are
|
|---|
| 10 | expected to change slightly over time, and even to grow as more is learned
|
|---|
| 11 | about obscure portability considerations. Two existing documents
|
|---|
| 12 | <code class="filename">samba/source/internals.doc</code> and
|
|---|
| 13 | <code class="filename">samba/source/architecture.doc</code> provide
|
|---|
| 14 | additional information.
|
|---|
| 15 | </p><p>
|
|---|
| 16 | The loosely related question of coding style is very personal and this
|
|---|
| 17 | document does not attempt to address that subject, except to say that I
|
|---|
| 18 | have observed that eight character tabs seem to be preferred in Samba
|
|---|
| 19 | source. If you are interested in the topic of coding style, two oft-quoted
|
|---|
| 20 | documents are:
|
|---|
| 21 | </p><p>
|
|---|
| 22 | <a class="ulink" href="http://lxr.linux.no/source/Documentation/CodingStyle" target="_top">http://lxr.linux.no/source/Documentation/CodingStyle</a>
|
|---|
| 23 | </p><p>
|
|---|
| 24 | <a class="ulink" href="http://www.fsf.org/prep/standards_toc.html" target="_top">http://www.fsf.org/prep/standards_toc.html</a>
|
|---|
| 25 | </p><p>
|
|---|
| 26 | But note that coding style in Samba varies due to the many different
|
|---|
| 27 | programmers who have contributed.
|
|---|
| 28 | </p><p>
|
|---|
| 29 | Following are some considerations you should use when adding new code to
|
|---|
| 30 | Samba. First and foremost remember that:
|
|---|
| 31 | </p><p>
|
|---|
| 32 | Portability is a primary consideration in adding function, as is network
|
|---|
| 33 | compatability with de facto, existing, real world CIFS/SMB implementations.
|
|---|
| 34 | There are lots of platforms that Samba builds on so use caution when adding
|
|---|
| 35 | a call to a library function that is not invoked in existing Samba code.
|
|---|
| 36 | Also note that there are many quite different SMB/CIFS clients that Samba
|
|---|
| 37 | tries to support, not all of which follow the SNIA CIFS Technical Reference
|
|---|
| 38 | (or the earlier Microsoft reference documents or the X/Open book on the SMB
|
|---|
| 39 | Standard) perfectly.
|
|---|
| 40 | </p><p>
|
|---|
| 41 | Here are some other suggestions:
|
|---|
| 42 | </p><div class="orderedlist"><ol type="1"><li><p>
|
|---|
| 43 | use d_printf instead of printf for display text
|
|---|
| 44 | reason: enable auto-substitution of translated language text
|
|---|
| 45 | </p></li><li><p>
|
|---|
| 46 | use SAFE_FREE instead of free
|
|---|
| 47 | reason: reduce traps due to null pointers
|
|---|
| 48 | </p></li><li><p>
|
|---|
| 49 | don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros
|
|---|
| 50 | reason: not POSIX
|
|---|
| 51 | </p></li><li><p>
|
|---|
| 52 | don't use strcpy and strlen (use safe_* equivalents)
|
|---|
| 53 | reason: to avoid traps due to buffer overruns
|
|---|
| 54 | </p></li><li><p>
|
|---|
| 55 | don't use getopt_long, use popt functions instead
|
|---|
| 56 | reason: portability
|
|---|
| 57 | </p></li><li><p>
|
|---|
| 58 | explicitly add const qualifiers on parm passing in functions where parm
|
|---|
| 59 | is input only (somewhat controversial but const can be #defined away)
|
|---|
| 60 | </p></li><li><p>
|
|---|
| 61 | when passing a va_list as an arg, or assigning one to another
|
|---|
| 62 | please use the VA_COPY() macro
|
|---|
| 63 | reason: on some platforms, va_list is a struct that must be
|
|---|
| 64 | initialized in each function...can SEGV if you don't.
|
|---|
| 65 | </p></li><li><p>
|
|---|
| 66 | discourage use of threads
|
|---|
| 67 | reason: portability (also see architecture.doc)
|
|---|
| 68 | </p></li><li><p>
|
|---|
| 69 | don't explicitly include new header files in C files - new h files
|
|---|
| 70 | should be included by adding them once to includes.h
|
|---|
| 71 | reason: consistency
|
|---|
| 72 | </p></li><li><p>
|
|---|
| 73 | don't explicitly extern functions (they are autogenerated by
|
|---|
| 74 | "make proto" into proto.h)
|
|---|
| 75 | reason: consistency
|
|---|
| 76 | </p></li><li><p>
|
|---|
| 77 | use endian safe macros when unpacking SMBs (see byteorder.h and
|
|---|
| 78 | internals.doc)
|
|---|
| 79 | reason: not everyone uses Intel
|
|---|
| 80 | </p></li><li><p>
|
|---|
| 81 | Note Unicode implications of charset handling (see internals.doc). See
|
|---|
| 82 | pull_* and push_* and convert_string functions.
|
|---|
| 83 | reason: Internationalization
|
|---|
| 84 | </p></li><li><p>
|
|---|
| 85 | Don't assume English only
|
|---|
| 86 | reason: See above
|
|---|
| 87 | </p></li><li><p>
|
|---|
| 88 | Try to avoid using in/out parameters (functions that return data which
|
|---|
| 89 | overwrites input parameters)
|
|---|
| 90 | reason: Can cause stability problems
|
|---|
| 91 | </p></li><li><p>
|
|---|
| 92 | Ensure copyright notices are correct, don't append Tridge's name to code
|
|---|
| 93 | that he didn't write. If you did not write the code, make sure that it
|
|---|
| 94 | can coexist with the rest of the Samba GPLed code.
|
|---|
| 95 | </p></li><li><p>
|
|---|
|
|---|
