Remove places that say if no language is specified it will default to english......
[asterisk/asterisk.git] / doc / CODING-GUIDELINES
index b68a200..990f5bc 100644 (file)
@@ -14,17 +14,15 @@ To be accepted into the codebase, all non-trivial changes must be
 disclaimed to Digium or placed in the public domain. For more information
 see http://bugs.digium.com
 
-Patches should be in the form of a unified (-u) diff, made from the directory
-above the top-level Asterisk source directory. For example:
+Patches should be in the form of a unified (-u) diff, made from a checkout
+from subversion.
 
-- the base code you are working from is in ~/work/asterisk-base
-- the changes are in ~/work/asterisk-new
+/usr/src/asterisk$ svn diff > mypatch
 
-~/work$ diff -urN asterisk-base asterisk-new
+If you would like to only include changes to certain files in the patch, you
+can list them in the "svn diff" command:
 
-If you are changing within a fresh CVS/SVN repository, you can create
-a patch with
-$ cvs diff -urN <mycodefile>.c
+/usr/src/asterisk$ svn diff somefile.c someotherfile.c > mypatch
 
 * General rules
 ---------------
@@ -70,6 +68,10 @@ $ cvs diff -urN <mycodefile>.c
   within Asterisk to enhance portability and in some cases to produce more
   secure and thread-safe code. Check utils.c/utils.h for these.
 
+- If you need to create a detached thread, use the ast_pthread_create_detached()
+  normally or ast_pthread_create_detached_background() for a thread with a smaller
+  stack size.  This reduces the replication of the code to handle the pthread_attr_t
+  structure.
 
 * Code formatting
 -----------------
@@ -172,7 +174,7 @@ Instead, try to minimize the number of lines of code that need to be
 indented, by only indenting the shortest case of the 'if'
 statement, like so:
 
-if !(foo) {
+if (!foo) {
        result = 0;
        return;
 }
@@ -208,6 +210,18 @@ alloca(), and similar functions do not _ever_ need to be cast to a specific
 type, and when you are passing a pointer to (for example) a callback function
 that accepts a 'void *' you do not need to cast into that type.
 
+* Function naming
+-----------------
+
+All public functions (those not marked 'static'), must be named "ast_<something>"
+and have a descriptive name.
+
+As an example, suppose you wanted to take a local function "find_feature", defined
+as static in a file, and used only in that file, and make it public, and use it
+in other files. You will have to remove the "static" declaration and define a 
+prototype in an appropriate header file (usually in include/asterisk). A more
+specific name should be given, such as "ast_find_call_feature".
+
 * Variable naming
 -----------------
 
@@ -227,11 +241,7 @@ options that they are in fact intended to be global.
 - Don't use un-necessary typedef's
 Don't use 'typedef' just to shorten the amount of typing; there is no substantial
 benefit in this:
-
-struct foo {
-       int bar;
-};
-typedef foo_t struct foo;
+struct foo { int bar; }; typedef foo_t struct foo;
 
 In fact, don't use 'variable type' suffixes at all; it's much preferable to
 just type 'struct foo' rather than 'foo_s'.
@@ -474,11 +484,19 @@ Note that /*! */ blocks document the construct immediately following them
 unless they are written, /*!< */, in which case they document the construct
 preceding them.
 
+It is very much preferred that documentation is not done inline, as done in
+the previous example for member2.  The first reason for this is that it tends
+to encourage extremely brief, and often pointless, documentation since people
+try to keep the comment from making the line extremely long.  However, if you
+insist on using inline comments, please indent the documentation with spaces!
+That way, all of the comments are properly aligned, regardless of what tab
+size is being used for viewing the code.
+
 * Finishing up before you submit your code
 ------------------------------------------
 
 - Look at the code once more
-When you achieve your desired functionalty, make another few refactor
+When you achieve your desired functionality, make another few refactor
 passes over the code to optimize it.
 
 - Read the patch