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.71.0"><link rel="start" 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> 2So you want to add code to Samba ... 3</p><p> 4One of the daunting tasks facing a programmer attempting to write code for 5Samba is understanding the various coding conventions used by those most 6active in the project. These conventions were mostly unwritten and helped 7improve either the portability, stability or consistency of the code. This 8document will attempt to document a few of the more important coding 9practices used at this time on the Samba project. The coding practices are 10expected to change slightly over time, and even to grow as more is learned 11about 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 14additional information. 15</p><p> 16The loosely related question of coding style is very personal and this 17document does not attempt to address that subject, except to say that I 18have observed that eight character tabs seem to be preferred in Samba 19source. If you are interested in the topic of coding style, two oft-quoted 20documents are: 21</p><p> 22<a href="http://lxr.linux.no/source/Documentation/CodingStyle" target="_top">http://lxr.linux.no/source/Documentation/CodingStyle</a> 23</p><p> 24<a href="http://www.fsf.org/prep/standards_toc.html" target="_top">http://www.fsf.org/prep/standards_toc.html</a> 25</p><p> 26But note that coding style in Samba varies due to the many different 27programmers who have contributed. 28</p><p> 29Following are some considerations you should use when adding new code to 30Samba. First and foremost remember that: 31</p><p> 32Portability is a primary consideration in adding function, as is network 33compatability with de facto, existing, real world CIFS/SMB implementations. 34There are lots of platforms that Samba builds on so use caution when adding 35a call to a library function that is not invoked in existing Samba code. 36Also note that there are many quite different SMB/CIFS clients that Samba 37tries 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 39Standard) perfectly. 40</p><p> 41Here 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> 96 Consider usage of DATA_BLOBs for length specified byte-data. 97 reason: stability 98</p></li><li><p> 99 Take advantage of tdbs for database like function 100 reason: consistency 101</p></li><li><p> 102 Don't access the SAM_ACCOUNT structure directly, they should be accessed 103 via pdb_get...() and pdb_set...() functions. 104 reason: stability, consistency 105</p></li><li><p> 106 Don't check a password directly against the passdb, always use the 107 check_password() interface. 108 reason: long term pluggability 109</p></li><li><p> 110 Try to use asprintf rather than pstrings and fstrings where possible 111</p></li><li><p> 112 Use normal C comments / * instead of C++ comments // like 113 this. Although the C++ comment format is part of the C99 114 standard, some older vendor C compilers do not accept it. 115</p></li><li><p> 116 Try to write documentation for API functions and structures 117 explaining the point of the code, the way it should be used, and 118 any special conditions or results. Mark these with a double-star 119 comment start / ** so that they can be picked up by Doxygen, as in 120 this file. 121</p></li><li><p> 122 Keep the scope narrow. This means making functions/variables 123 static whenever possible. We don't want our namespace 124 polluted. Each module should have a minimal number of externally 125 visible functions or variables. 126</p></li><li><p> 127 Use function pointers to keep knowledge about particular pieces of 128 code isolated in one place. We don't want a particular piece of 129 functionality to be spread out across lots of places - that makes 130 for fragile, hand to maintain code. Instead, design an interface 131 and use tables containing function pointers to implement specific 132 functionality. This is particularly important for command 133 interpreters. 134</p></li><li><p> 135 Think carefully about what it will be like for someone else to add 136 to and maintain your code. If it would be hard for someone else to 137 maintain then do it another way. 138</p></li></ol></div><p> 139The suggestions above are simply that, suggestions, but the information may 140help in reducing the routine rework done on new code. The preceeding list 141is expected to change routinely as new support routines and macros are 142added. 143</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="internals.html">Prev</a>�</td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right">�<a accesskey="n" href="contributing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter�5.�Samba Internals�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Chapter�7.�Contributing code</td></tr></table></div></body></html> 144