[Pkg-gnupg-commit] [gnupg2] 39/292: doc: Add a few extra coding standard notes.

[Daniel Kahn Gillmor]

This is an automated email from the git hooks/post-receive script.

dkg pushed a commit to branch master
in repository gnupg2.

commit 05e488943ca5d980b9bda2f21426cc7a17b41410
Author: Werner Koch <wk at gnupg.org>
Date:   Tue Sep 20 08:55:04 2016 +0200

    doc: Add a few extra coding standard notes.
    
    --
    
    Signed-off-by: Werner Koch <wk at gnupg.org>
---
 doc/HACKING | 51 ++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 38 insertions(+), 13 deletions(-)

diff --git a/doc/HACKING b/doc/HACKING
index 1888b29..bb04fdf 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -38,28 +38,31 @@ are delimited by a comma (e.g. =scd,w32:=). Commonly found keywords
 are
 
  - agent   :: The gpg-agent component
- - ssh     :: The ssh-agent part of the agent
+ - build   :: Changes to the build system
+ - ccid    :: The CCID driver in scdaemon
  - common  :: Code in common
- - iobuf   :: The IOBUF system in common
+ - dirmngr :: The dirmngr component
+ - doc     :: Documentation changes
  - gpg     :: The gpg or gpgv components
- - gpgsm   :: The gpgsm component
+ - sm      :: The gpgsm component (also "gpgsm")
+ - gpgscm  :: The regression test driver
+ - indent  :: Indentation and similar changes
+ - iobuf   :: The IOBUF system in common
+ - po      :: Translations
  - scd     :: The scdaemon component
- - ccid    :: The CCID driver in scdaemon
- - dirmngr :: The dirmngr component
- - wks     :: The web key service tools
+ - speedo  :: Speedo build system specific changes
+ - ssh     :: The ssh-agent part of the agent
+ - tests   :: The regressions tests
  - tools   :: Other code in tools
  - w32     :: Windows related code
- - po      :: Translations
- - build   :: Changes to the build system
- - speedo  :: Speedo build system specific changes
- - doc     :: Documentation changes
- - indent  :: Indentation and similar changes
+ - wks     :: The web key service tools
+ - yat2m   :: The yat2m tool.
 
 Typo fixes and documentation updates don't need a ChangeLog entry;
 thus you would use a commit message like
 
 #+begin_example
-Fix typo in a comment
+doc: Fix typo in a comment
 
 --
 #+end_example
@@ -128,9 +131,28 @@ Note that such a comment will be removed if the git commit option
   - Only certain C99 features may be used (see below); in general
     stick to C90.
   - Please do not use C++ =//= style comments.
+  - Do not use comments like:
+#+begin_src
+      if (foo)
+        /* Now that we know that foo is true we can call bar.  */
+        bar ();
+#+end_src
+    instead write the comment on the if line or before it.  You may
+    also use a block and put the comment inside.
+  - Please use asterisks on the left of longer comments.  This makes
+    it easier to read without syntax highlighting, on printouts, and
+    for blind people.
   - Try to fit lines into 80 columns.
   - Ignore signed/unsigned pointer mismatches
   - No arithmetic on void pointers; cast to char* first.
+  - Do not use
+#+begin_src
+      if ( 42 == foo )
+#+end_src
+    this is harder to read and modern compilers are pretty good in
+    detecing accidential assignments.  It is also suggested not to
+    compare to 0 or NULL but to test the value direct or with a '!';
+    this makes it easier to see that a boolean test is done.
   - We use our own printf style functions like =es_printf=, and
     =gpgrt_asprintf= (or the =es_asprintf= macro) which implement most
     C99 features with the exception of =wchar_t= (which should anyway
@@ -145,12 +167,15 @@ Note that such a comment will be removed if the git commit option
   - Always use xfree() instead of free().  If it is not easy to see
     that the freed variable is not anymore used, explicitly set the
     variable to NULL.
+  - New code shall in general use xtrymalloc or xtrycalloc and check
+    for an error (use gpg_error_from_errno()).
   - Init function local variables only if needed so that the compiler
     can do a better job in detecting uninitialized variables which may
     indicate a problem with the code.
   - Never init static or file local variables to 0 to make sure they
     end up in BSS.
-  - Use --enable-maintainer-mode with configure.
+  - Use --enable-maintainer-mode with configure so that all suitable
+    warnings are enabled.
 
 ** Variable names
 

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-gnupg/gnupg2.git