1 Return-Path: <bremner@tethera.net>
\r
2 X-Original-To: notmuch@notmuchmail.org
\r
3 Delivered-To: notmuch@notmuchmail.org
\r
4 Received: from localhost (localhost [127.0.0.1])
\r
5 by olra.theworths.org (Postfix) with ESMTP id C284F431FB6
\r
6 for <notmuch@notmuchmail.org>; Fri, 27 Jan 2012 15:47:19 -0800 (PST)
\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
\r
11 X-Spam-Status: No, score=-2.3 tagged_above=-999 required=5
\r
12 tests=[RCVD_IN_DNSWL_MED=-2.3] autolearn=disabled
\r
13 Received: from olra.theworths.org ([127.0.0.1])
\r
14 by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)
\r
15 with ESMTP id FgTAohoPEYM0 for <notmuch@notmuchmail.org>;
\r
16 Fri, 27 Jan 2012 15:47:19 -0800 (PST)
\r
17 Received: from tempo.its.unb.ca (tempo.its.unb.ca [131.202.1.21])
\r
18 (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
\r
19 (No client certificate requested)
\r
20 by olra.theworths.org (Postfix) with ESMTPS id 1369B431FAE
\r
21 for <notmuch@notmuchmail.org>; Fri, 27 Jan 2012 15:47:18 -0800 (PST)
\r
22 Received: from zancas.localnet
\r
23 (fctnnbsc36w-156034071197.pppoe-dynamic.High-Speed.nb.bellaliant.net
\r
24 [156.34.71.197]) (authenticated bits=0)
\r
25 by tempo.its.unb.ca (8.13.8/8.13.8) with ESMTP id q0RNlClT020517
\r
26 (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NO);
\r
27 Fri, 27 Jan 2012 19:47:14 -0400
\r
28 Received: from bremner by zancas.localnet with local (Exim 4.77)
\r
29 (envelope-from <bremner@tethera.net>)
\r
30 id 1RqvVg-0000IP-In; Fri, 27 Jan 2012 19:47:12 -0400
\r
31 From: David Bremner <david@tethera.net>
\r
32 To: notmuch@notmuchmail.org
\r
33 Subject: [PATCH] STYLE: Initial draft of coding style document
\r
34 Date: Fri, 27 Jan 2012 19:46:58 -0400
\r
35 Message-Id: <1327708018-1107-1-git-send-email-david@tethera.net>
\r
36 X-Mailer: git-send-email 1.7.8.3
\r
37 Cc: David Bremner <bremner@debian.org>
\r
38 X-BeenThere: notmuch@notmuchmail.org
\r
39 X-Mailman-Version: 2.1.13
\r
41 List-Id: "Use and development of the notmuch mail system."
\r
42 <notmuch.notmuchmail.org>
\r
43 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
44 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
45 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
46 List-Post: <mailto:notmuch@notmuchmail.org>
\r
47 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
48 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
49 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
50 X-List-Received-Date: Fri, 27 Jan 2012 23:47:19 -0000
\r
52 From: David Bremner <bremner@debian.org>
\r
54 This was edited by (at least) Austin, Tomi, and myself.
\r
56 devel/STYLE | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\r
57 1 files changed, 87 insertions(+), 0 deletions(-)
\r
58 create mode 100644 devel/STYLE
\r
60 diff --git a/devel/STYLE b/devel/STYLE
\r
61 new file mode 100644
\r
62 index 0000000..7ef3209
\r
72 +There is a file uncrustify.cfg in this directory that can be used to
\r
73 +approximate the prevailing code style. You can run it with e.g.
\r
75 + uncrustify --replace -c devel/uncrustify.cfg foo.c
\r
77 +You still have to use your judgement about accepting or rejecting the
\r
78 +changes uncrustify makes. With a nice git frontend, you can add the
\r
79 +lines you agree with and reject the rest.
\r
81 +For Emacs users, the file .dir-locals.el in the top level source
\r
82 +directory will configure c-mode to automatically meet most of the
\r
83 +basic layout rules. I
\r
85 +Indentation, Whitespace, and Layout
\r
86 +-----------------------------------
\r
88 +The following nonsense code demonstrates many aspects of the style:
\r
91 +function (param_type param, param_type param)
\r
95 + for (i = 0; i < 10; i++) {
\r
100 + some_other_func (j, i);
\r
104 +* Indent is 4 spaces with mixed tabs/spaces and a tab width of 8.
\r
105 + Tabs should be only at the beginning of the line.
\r
107 +* Use copious whitespace. In particular
\r
108 + - there is a space between the function name and the open paren in a call.
\r
109 + - likewise, there is a space following keywords such as if and while
\r
110 + - every binary operator should have space on either side.
\r
112 +* No trailing whitespace. Please enable the standard pre-commit hook
\r
113 + in git (or an equivalent hook).
\r
115 +* The name in a function prototype should start at the beginning of a line.
\r
117 +* Opening braces "cuddle" (they are on the same line as the
\r
118 + if/for/while test) and are preceded by a space. The opening brace of
\r
119 + functions is the exception, and starts on a new line.
\r
121 +* Comments are always C-style /* */ block comments. They should start
\r
122 + with a capital letter and generally be written in complete
\r
123 + sentences. Public library functions are documented immediately
\r
124 + before their prototype in lib/notmuch.h. Internal functions are
\r
125 + typically documented immediately before their definition.
\r
127 +* Code lines should be less than 80 columns and comments should be
\r
128 + wrapped at 70 columns.
\r
133 +* Use lowercase_with_underscores for function, variable, and type
\r
136 +* All structs should be typedef'd to a name ending with _t. If the
\r
137 + struct has a tag, it should be the same as the typedef name, minus
\r
140 +libnotmuch conventions
\r
141 +----------------------------------
\r
143 +* Functions starting with notmuch_ in lib/notmuch.h are public and are
\r
144 + automatically exported from the shared library. Private library
\r
145 + functions should generally either be static or, if they are shared
\r
146 + between compilation units, start with _notmuch.
\r
148 +* Functions in libnotmuch must not access user configuration files
\r
149 + (i.e. .notmuch-config)
\r
151 +* Code which needs to be accessed from both the CLI and from
\r
152 + libnotmuch should be factored out into libutil (under util/).
\r