From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from localhost (localhost [127.0.0.1]) by olra.theworths.org (Postfix) with ESMTP id C284F431FB6 for ; Fri, 27 Jan 2012 15:47:19 -0800 (PST) X-Virus-Scanned: Debian amavisd-new at olra.theworths.org X-Spam-Flag: NO X-Spam-Score: -2.3 X-Spam-Level: X-Spam-Status: No, score=-2.3 tagged_above=-999 required=5 tests=[RCVD_IN_DNSWL_MED=-2.3] autolearn=disabled Received: from olra.theworths.org ([127.0.0.1]) by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id FgTAohoPEYM0 for ; Fri, 27 Jan 2012 15:47:19 -0800 (PST) Received: from tempo.its.unb.ca (tempo.its.unb.ca [131.202.1.21]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by olra.theworths.org (Postfix) with ESMTPS id 1369B431FAE for ; Fri, 27 Jan 2012 15:47:18 -0800 (PST) Received: from zancas.localnet (fctnnbsc36w-156034071197.pppoe-dynamic.High-Speed.nb.bellaliant.net [156.34.71.197]) (authenticated bits=0) by tempo.its.unb.ca (8.13.8/8.13.8) with ESMTP id q0RNlClT020517 (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NO); Fri, 27 Jan 2012 19:47:14 -0400 Received: from bremner by zancas.localnet with local (Exim 4.77) (envelope-from ) id 1RqvVg-0000IP-In; Fri, 27 Jan 2012 19:47:12 -0400 From: David Bremner To: notmuch@notmuchmail.org Subject: [PATCH] STYLE: Initial draft of coding style document Date: Fri, 27 Jan 2012 19:46:58 -0400 Message-Id: <1327708018-1107-1-git-send-email-david@tethera.net> X-Mailer: git-send-email 1.7.8.3 Cc: David Bremner X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.13 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 27 Jan 2012 23:47:19 -0000 From: David Bremner This was edited by (at least) Austin, Tomi, and myself. --- devel/STYLE | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 87 insertions(+), 0 deletions(-) create mode 100644 devel/STYLE diff --git a/devel/STYLE b/devel/STYLE new file mode 100644 index 0000000..7ef3209 --- /dev/null +++ b/devel/STYLE @@ -0,0 +1,87 @@ +C/C++ coding style +================== + +Tools +----- + +There is a file uncrustify.cfg in this directory that can be used to +approximate the prevailing code style. You can run it with e.g. + + uncrustify --replace -c devel/uncrustify.cfg foo.c + +You still have to use your judgement about accepting or rejecting the +changes uncrustify makes. With a nice git frontend, you can add the +lines you agree with and reject the rest. + +For Emacs users, the file .dir-locals.el in the top level source +directory will configure c-mode to automatically meet most of the +basic layout rules. I + +Indentation, Whitespace, and Layout +----------------------------------- + +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++) { + int j; + + j = i + 10; + + some_other_func (j, i); + } +} + +* Indent is 4 spaces with mixed tabs/spaces and a tab width of 8. + Tabs should be only at the beginning of the line. + +* Use copious whitespace. In particular + - there is a space between the function name and the open paren in a call. + - 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). + +* The name in a function prototype should start at the beginning of a line. + +* Opening braces "cuddle" (they are on the same line as the + if/for/while test) and are preceded by a space. The opening brace of + functions is the exception, and starts on a new line. + +* Comments are always C-style /* */ block comments. They should start + with a capital letter and generally be written in complete + sentences. Public library functions are documented immediately + before their prototype in lib/notmuch.h. Internal functions are + typically documented immediately before their definition. + +* Code lines should be less than 80 columns and comments should be + wrapped at 70 columns. + +Naming +------ + +* Use lowercase_with_underscores for function, variable, and type + names. + +* 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. + +libnotmuch conventions +---------------------------------- + +* Functions starting with notmuch_ in lib/notmuch.h are public and are + automatically exported from the shared library. Private library + functions should generally either be static or, if they are shared + between compilation units, start with _notmuch. + +* Functions in libnotmuch must not access user configuration files + (i.e. .notmuch-config) + +* Code which needs to be accessed from both the CLI and from + libnotmuch should be factored out into libutil (under util/). -- 1.7.8.3