From 05e488943ca5d980b9bda2f21426cc7a17b41410 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Tue, 20 Sep 2016 08:55:04 +0200 Subject: [PATCH] doc: Add a few extra coding standard notes. -- Signed-off-by: Werner Koch --- doc/HACKING | 53 +++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 14 deletions(-) diff --git a/doc/HACKING b/doc/HACKING index 1888b29e6..bb04fdf6b 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 - - 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