X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=devel%2FSTYLE;h=da6531248feb7e827c6f5066faaf1049a61a2652;hp=094f71d1908f75b48f3d1ae77a4fbae9d260acb2;hb=2e86a4da55c29e0751d950839cdcbe40234ca8ba;hpb=022a2810809ffba4a7bcb71ed3483d2cb29d1c77

diff --git a/devel/STYLE b/devel/STYLE
index 094f71d1..da653124 100644
--- a/devel/STYLE
+++ b/devel/STYLE
@@ -25,9 +25,7 @@ The following nonsense code demonstrates many aspects of the style:
 static some_type
 function (param_type param, param_type param)
 {
-   int i;
-
-   for (i = 0; i < 10; i++) {
+   for (int i = 0; i < 10; i++) {
        int j;
 
        j = i + 10;
@@ -45,8 +43,9 @@ function (param_type param, param_type param)
    - likewise, there is a space following keywords such as if and while
    - every binary operator should have space on either side.
 
-* No trailing whitespace. Please enable the standard pre-commit hook
-  in git (or an equivalent hook).
+* No trailing whitespace. Please enable the standard pre-commit hook in git
+  (or an equivalent hook). The standard pre-commit hook is enabled by simply
+  renaming file '.git/hooks/pre-commit.sample' to '.git/hooks/pre-commit' .
 
 * The name in a function prototype should start at the beginning of a line.
 
@@ -63,16 +62,29 @@ function (param_type param, param_type param)
 * Code lines should be less than 80 columns and comments should be
   wrapped at 70 columns.
 
+* Variable declarations should be at the top of a block; C99 style
+  control variable declarations in for loops are also OK.
+
 Naming
 ------
 
 * Use lowercase_with_underscores for function, variable, and type
   names.
 
+* Except for variables with extremely small scope, and perhaps loop
+  indices, when naming variables and functions, err on the side of
+  verbosity.
+
 * All structs should be typedef'd to a name ending with _t.  If the
   struct has a tag, it should be the same as the typedef name, minus
   the trailing _t.
 
+CLI conventions
+---------------
+
+* Any changes to the JSON output format of search or show need an
+  accompanying change to devel/schemata.
+
 libnotmuch conventions
 ----------------------------------
 
@@ -86,3 +98,13 @@ libnotmuch conventions
 
 * Code which needs to be accessed from both the CLI and from
   libnotmuch should be factored out into libutil (under util/).
+
+* Deprecated functions should be marked with the NOTMUCH_DEPRECATED
+  macro which generates run time warnings with gcc and clang. In order
+  not to confuse doxygen this should go at the beginning of the
+  declaration like:
+
+  NOTMUCH_DEPRECATED(major,minor) notmuch_status_t notmuch_dwim(void *arg);
+
+  The @deprecated doxygen command can be used to generate markup in
+  the API docs.