- Timestamp:
- Mar 1, 2010, 3:05:48 PM (15 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
branches/samba-3.3.x/docs/htmldocs/Samba3-Developers-Guide/CodingSuggestions.html
r368 r411 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.7 5.2"><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" title="Chapter 6. Coding Suggestions"><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>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 2 So you want to add code to Samba ... 3 3 </p><p> … … 40 40 </p><p> 41 41 Here are some other suggestions: 42 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>42 </p><div class="orderedlist"><ol type="1"><li><p> 43 43 use d_printf instead of printf for display text 44 44 reason: enable auto-substitution of translated language text 45 </p></li><li class="listitem"><p>45 </p></li><li><p> 46 46 use SAFE_FREE instead of free 47 47 reason: reduce traps due to null pointers 48 </p></li><li class="listitem"><p>48 </p></li><li><p> 49 49 don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros 50 50 reason: not POSIX 51 </p></li><li class="listitem"><p>51 </p></li><li><p> 52 52 don't use strcpy and strlen (use safe_* equivalents) 53 53 reason: to avoid traps due to buffer overruns 54 </p></li><li class="listitem"><p>54 </p></li><li><p> 55 55 don't use getopt_long, use popt functions instead 56 56 reason: portability 57 </p></li><li class="listitem"><p>57 </p></li><li><p> 58 58 explicitly add const qualifiers on parm passing in functions where parm 59 59 is input only (somewhat controversial but const can be #defined away) 60 </p></li><li class="listitem"><p>60 </p></li><li><p> 61 61 when passing a va_list as an arg, or assigning one to another 62 62 please use the VA_COPY() macro 63 63 reason: on some platforms, va_list is a struct that must be 64 64 initialized in each function...can SEGV if you don't. 65 </p></li><li class="listitem"><p>65 </p></li><li><p> 66 66 discourage use of threads 67 67 reason: portability (also see architecture.doc) 68 </p></li><li class="listitem"><p>68 </p></li><li><p> 69 69 don't explicitly include new header files in C files - new h files 70 70 should be included by adding them once to includes.h 71 71 reason: consistency 72 </p></li><li class="listitem"><p>72 </p></li><li><p> 73 73 don't explicitly extern functions (they are autogenerated by 74 74 "make proto" into proto.h) 75 75 reason: consistency 76 </p></li><li class="listitem"><p>76 </p></li><li><p> 77 77 use endian safe macros when unpacking SMBs (see byteorder.h and 78 78 internals.doc) 79 79 reason: not everyone uses Intel 80 </p></li><li class="listitem"><p>80 </p></li><li><p> 81 81 Note Unicode implications of charset handling (see internals.doc). See 82 82 pull_* and push_* and convert_string functions. 83 83 reason: Internationalization 84 </p></li><li class="listitem"><p>84 </p></li><li><p> 85 85 Don't assume English only 86 86 reason: See above 87 </p></li><li class="listitem"><p>87 </p></li><li><p> 88 88 Try to avoid using in/out parameters (functions that return data which 89 89 overwrites input parameters) 90 90 reason: Can cause stability problems 91 </p></li><li class="listitem"><p>91 </p></li><li><p> 92 92 Ensure copyright notices are correct, don't append Tridge's name to code 93 93 that he didn't write. If you did not write the code, make sure that it 94 94 can coexist with the rest of the Samba GPLed code. 95 </p></li><li class="listitem"><p>95 </p></li><li><p> 96 96 Consider usage of DATA_BLOBs for length specified byte-data. 97 97 reason: stability 98 </p></li><li class="listitem"><p>98 </p></li><li><p> 99 99 Take advantage of tdbs for database like function 100 100 reason: consistency 101 </p></li><li class="listitem"><p>101 </p></li><li><p> 102 102 Don't access the SAM_ACCOUNT structure directly, they should be accessed 103 103 via pdb_get...() and pdb_set...() functions. 104 104 reason: stability, consistency 105 </p></li><li class="listitem"><p>105 </p></li><li><p> 106 106 Don't check a password directly against the passdb, always use the 107 107 check_password() interface. 108 108 reason: long term pluggability 109 </p></li><li class="listitem"><p>109 </p></li><li><p> 110 110 Try to use asprintf rather than pstrings and fstrings where possible 111 </p></li><li class="listitem"><p>111 </p></li><li><p> 112 112 Use normal C comments / * instead of C++ comments // like 113 113 this. Although the C++ comment format is part of the C99 114 114 standard, some older vendor C compilers do not accept it. 115 </p></li><li class="listitem"><p>115 </p></li><li><p> 116 116 Try to write documentation for API functions and structures 117 117 explaining the point of the code, the way it should be used, and … … 119 119 comment start / ** so that they can be picked up by Doxygen, as in 120 120 this file. 121 </p></li><li class="listitem"><p>121 </p></li><li><p> 122 122 Keep the scope narrow. This means making functions/variables 123 123 static whenever possible. We don't want our namespace 124 124 polluted. Each module should have a minimal number of externally 125 125 visible functions or variables. 126 </p></li><li class="listitem"><p>126 </p></li><li><p> 127 127 Use function pointers to keep knowledge about particular pieces of 128 128 code isolated in one place. We don't want a particular piece of … … 132 132 functionality. This is particularly important for command 133 133 interpreters. 134 </p></li><li class="listitem"><p>134 </p></li><li><p> 135 135 Think carefully about what it will be like for someone else to add 136 136 to and maintain your code. If it would be hard for someone else to
Note:
See TracChangeset
for help on using the changeset viewer.
