doc: Add a few extra coding standard notes.

--

Signed-off-by: Werner Koch <wk@gnupg.org>

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
- - common  :: Code in common
- - iobuf   :: The IOBUF system in common
- - gpg     :: The gpg or gpgv components
- - gpgsm   :: The gpgsm component
- - scd     :: The scdaemon component
+ - build   :: Changes to the build system
  - ccid    :: The CCID driver in scdaemon
+ - common  :: Code in common
  - dirmngr :: The dirmngr component
- - wks     :: The web key service tools
+ - doc     :: Documentation changes
+ - gpg     :: The gpg or gpgv components
+ - 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
+ - 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