summaryrefslogtreecommitdiff
path: root/docs/htmldocs/Samba3-Developers-Guide/CodingSuggestions.html
diff options
context:
space:
mode:
authorIvo De Decker <ivo.dedecker@ugent.be>2013-05-10 13:33:02 +0200
committerIvo De Decker <ivo.dedecker@ugent.be>2013-05-10 13:33:02 +0200
commit31202ad025bcdeb2585d18dc3f4641b5cf9c0ec4 (patch)
tree32c20d66684ac97b86e55495146e9a676bfae85a /docs/htmldocs/Samba3-Developers-Guide/CodingSuggestions.html
parent2865eba17fddda6c49f1209ca92d539111e7ff93 (diff)
downloadsamba-31202ad025bcdeb2585d18dc3f4641b5cf9c0ec4.tar.gz
Imported Upstream version 4.0.0+dfsg1upstream/4.0.0+dfsg1
Diffstat (limited to 'docs/htmldocs/Samba3-Developers-Guide/CodingSuggestions.html')
-rw-r--r--docs/htmldocs/Samba3-Developers-Guide/CodingSuggestions.html143
1 files changed, 0 insertions, 143 deletions
diff --git a/docs/htmldocs/Samba3-Developers-Guide/CodingSuggestions.html b/docs/htmldocs/Samba3-Developers-Guide/CodingSuggestions.html
deleted file mode 100644
index f4c5744e3a..0000000000
--- a/docs/htmldocs/Samba3-Developers-Guide/CodingSuggestions.html
+++ /dev/null
@@ -1,143 +0,0 @@
-<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.75.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>
-So you want to add code to Samba ...
-</p><p>
-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
-<code class="filename">samba/source/internals.doc</code> and
-<code class="filename">samba/source/architecture.doc</code> provide
-additional information.
-</p><p>
-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:
-</p><p>
-<a class="ulink" href="http://lxr.linux.no/source/Documentation/CodingStyle" target="_top">http://lxr.linux.no/source/Documentation/CodingStyle</a>
-</p><p>
-<a class="ulink" href="http://www.fsf.org/prep/standards_toc.html" target="_top">http://www.fsf.org/prep/standards_toc.html</a>
-</p><p>
-But note that coding style in Samba varies due to the many different
-programmers who have contributed.
-</p><p>
-Following are some considerations you should use when adding new code to
-Samba. First and foremost remember that:
-</p><p>
-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.
-</p><p>
-Here are some other suggestions:
-</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
- use d_printf instead of printf for display text
- reason: enable auto-substitution of translated language text
-</p></li><li class="listitem"><p>
- use SAFE_FREE instead of free
- reason: reduce traps due to null pointers
-</p></li><li class="listitem"><p>
- don't use bzero use memset, or ZERO_STRUCT and ZERO_STRUCTP macros
- reason: not POSIX
-</p></li><li class="listitem"><p>
- don't use strcpy and strlen (use safe_* equivalents)
- reason: to avoid traps due to buffer overruns
-</p></li><li class="listitem"><p>
- don't use getopt_long, use popt functions instead
- reason: portability
-</p></li><li class="listitem"><p>
- explicitly add const qualifiers on parm passing in functions where parm
- is input only (somewhat controversial but const can be #defined away)
-</p></li><li class="listitem"><p>
- 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.
-</p></li><li class="listitem"><p>
- discourage use of threads
- reason: portability (also see architecture.doc)
-</p></li><li class="listitem"><p>
- 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
-</p></li><li class="listitem"><p>
- don't explicitly extern functions (they are autogenerated by
- "make proto" into proto.h)
- reason: consistency
-</p></li><li class="listitem"><p>
- use endian safe macros when unpacking SMBs (see byteorder.h and
- internals.doc)
- reason: not everyone uses Intel
-</p></li><li class="listitem"><p>
- Note Unicode implications of charset handling (see internals.doc). See
- pull_* and push_* and convert_string functions.
- reason: Internationalization
-</p></li><li class="listitem"><p>
- Don't assume English only
- reason: See above
-</p></li><li class="listitem"><p>
- Try to avoid using in/out parameters (functions that return data which
- overwrites input parameters)
- reason: Can cause stability problems
-</p></li><li class="listitem"><p>
- Ensure copyright notices are correct, don't append Tridge's name to code
- that he didn't write. If you did not write the code, make sure that it
- can coexist with the rest of the Samba GPLed code.
-</p></li><li class="listitem"><p>
- Consider usage of DATA_BLOBs for length specified byte-data.
- reason: stability
-</p></li><li class="listitem"><p>
- Take advantage of tdbs for database like function
- reason: consistency
-</p></li><li class="listitem"><p>
- Don't access the SAM_ACCOUNT structure directly, they should be accessed
- via pdb_get...() and pdb_set...() functions.
- reason: stability, consistency
-</p></li><li class="listitem"><p>
- Don't check a password directly against the passdb, always use the
- check_password() interface.
- reason: long term pluggability
-</p></li><li class="listitem"><p>
- Try to use asprintf rather than pstrings and fstrings where possible
-</p></li><li class="listitem"><p>
- Use normal C comments / * instead of C++ comments // like
- this. Although the C++ comment format is part of the C99
- standard, some older vendor C compilers do not accept it.
-</p></li><li class="listitem"><p>
- Try to write documentation for API functions and structures
- explaining the point of the code, the way it should be used, and
- any special conditions or results. Mark these with a double-star
- comment start / ** so that they can be picked up by Doxygen, as in
- this file.
-</p></li><li class="listitem"><p>
- Keep the scope narrow. This means making functions/variables
- static whenever possible. We don't want our namespace
- polluted. Each module should have a minimal number of externally
- visible functions or variables.
-</p></li><li class="listitem"><p>
- Use function pointers to keep knowledge about particular pieces of
- code isolated in one place. We don't want a particular piece of
- functionality to be spread out across lots of places - that makes
- for fragile, hand to maintain code. Instead, design an interface
- and use tables containing function pointers to implement specific
- functionality. This is particularly important for command
- interpreters.
-</p></li><li class="listitem"><p>
- Think carefully about what it will be like for someone else to add
- to and maintain your code. If it would be hard for someone else to
- maintain then do it another way.
-</p></li></ol></div><p>
-The suggestions above are simply that, suggestions, but the information may
-help in reducing the routine rework done on new code. The preceeding list
-is expected to change routinely as new support routines and macros are
-added.
-</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>
generated by cgit v1.2.3 (git 2.39.1) at 2025-05-02 00:00:26 +0000