Re: [PATCH] emacs: do not change users' mail agent configuration

[notmuch-archives.git] / 6f / 4034dc2bdf6f126f29eeffd4339627fde9817f

Return-Path: <polatel@gmail.com>\r
X-Original-To: notmuch@notmuchmail.org\r
Delivered-To: notmuch@notmuchmail.org\r
Received: from localhost (localhost [127.0.0.1])\r
        by olra.theworths.org (Postfix) with ESMTP id 69D3A431FBC\r
        for <notmuch@notmuchmail.org>; Wed, 13 Jan 2010 05:40:53 -0800 (PST)\r
X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
X-Spam-Flag: NO\r
X-Spam-Score: 0.046\r
X-Spam-Level: \r
X-Spam-Status: No, score=0.046 tagged_above=-999 required=5 tests=[AWL=-0.574,\r
        BAYES_50=0.001, RCVD_IN_SORBS_WEB=0.619] autolearn=no\r
Received: from olra.theworths.org ([127.0.0.1])\r
        by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
        with ESMTP id 6Gn52KVE5+IO for <notmuch@notmuchmail.org>;\r
        Wed, 13 Jan 2010 05:40:52 -0800 (PST)\r
Received: from mail-bw0-f224.google.com (mail-bw0-f224.google.com\r
        [209.85.218.224])\r
        by olra.theworths.org (Postfix) with ESMTP id 5B57B431FAE\r
        for <notmuch@notmuchmail.org>; Wed, 13 Jan 2010 05:40:52 -0800 (PST)\r
Received: by bwz24 with SMTP id 24so15214459bwz.30\r
        for <notmuch@notmuchmail.org>; Wed, 13 Jan 2010 05:40:51 -0800 (PST)\r
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma;\r
        h=domainkey-signature:received:received:sender:from:to:subject:date\r
        :message-id:x-mailer:organization;\r
        bh=rtPfbUZNu2K1RvXWAn89qEvCJAiYRaQrzc2HJAY3Kgw=;\r
        b=Q1p/WzyXpqW6hSCUUbA4RhE4HtV8l6au2hmPbtU07JXhtN0IpOpwhkOQ16rosLAEGR\r
        UCcggM1+Lk2x7atnGE5ZFAUqFthiA85vY4q9vD2EXrX8QYyOPuG+UdTlFxIiw05flKHf\r
        BFUDkpi//qP07Cez9rPGNXw+yBueMlRF1XrZU=\r
DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma;\r
        h=sender:from:to:subject:date:message-id:x-mailer:organization;\r
        b=fEvuFDF4WDHNnGZArhIP4ZPnN/QM9WQeoMtywvtScCtgzOtO3gA+GDN2N7PjDCymup\r
        NTiI43utgLmiiqlaL67N111ySJrs1Y1Op9KWggsVNOt7N/205qZIi+gdBySwc1yhqAmm\r
        NR05v43IvuW3zXeBtC3pMbqIcPvqDJj/mo12Q=\r
Received: by 10.204.27.16 with SMTP id g16mr2569252bkc.97.1263390051237;\r
        Wed, 13 Jan 2010 05:40:51 -0800 (PST)\r
Received: from harikalardiyari ([78.179.54.193])\r
        by mx.google.com with ESMTPS id 14sm3618297bwz.1.2010.01.13.05.40.49\r
        (version=TLSv1/SSLv3 cipher=RC4-MD5);\r
        Wed, 13 Jan 2010 05:40:50 -0800 (PST)\r
Sender: Ali Polatel <polatel@gmail.com>\r
From: Ali Polatel <alip@exherbo.org>\r
To: notmuch@notmuchmail.org\r
Date: Wed, 13 Jan 2010 15:40:42 +0200\r
Message-Id:\r
 <24296f98dcf960342b02d2e1bbb303fd0ad4fa67.1263389936.git.alip@exherbo.org>\r
X-Mailer: git-send-email 1.6.6\r
Organization: Pink Floyd\r
Subject: [notmuch] [PATCH] Import CODING_STYLE from cairo\r
X-BeenThere: notmuch@notmuchmail.org\r
X-Mailman-Version: 2.1.13\r
Precedence: list\r
List-Id: "Use and development of the notmuch mail system."\r
        <notmuch.notmuchmail.org>\r
List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
        <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
List-Post: <mailto:notmuch@notmuchmail.org>\r
List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
        <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
X-List-Received-Date: Wed, 13 Jan 2010 13:40:53 -0000\r
\r
A good way to let new contributors know how to contribute :)\r
---\r
 CODING_STYLE |  291 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++\r
 1 files changed, 291 insertions(+), 0 deletions(-)\r
 create mode 100644 CODING_STYLE\r
\r
diff --git a/CODING_STYLE b/CODING_STYLE\r
new file mode 100644\r
index 0000000..95ceac0\r
--- /dev/null\r
+++ b/CODING_STYLE\r
@@ -0,0 +1,291 @@\r
+Cairo coding style.\r
+\r
+This document is intended to be a short description of the preferred\r
+coding style for the cairo source code. Good style requires good\r
+taste, which means this can't all be reduced to automated rules, and\r
+there are exceptions.\r
+\r
+We want the code to be easy to understand and maintain, and consistent\r
+style plays an important part in that, even if some of the specific\r
+details seem trivial. If nothing else, this document gives a place to\r
+put consistent answers for issues that would otherwise be arbitrary.\r
+\r
+Most of the guidelines here are demonstrated by examples, (which means\r
+this document is quicker to read than it might appear given its\r
+length). Most of the examples are positive examples that you should\r
+imitate. The few negative examples are clearly marked with a comment\r
+of /* Yuck! */. Please don't submit code to cairo that looks like any\r
+of these.\r
+\r
+Indentation\r
+-----------\r
+Each new level is indented 4 more spaces than the previous level:\r
+\r
+       if (condition)\r
+           do_something ();\r
+\r
+This may be achieved with space characters or a combination of tab\r
+characters and space characters. It may not be achieved with tab\r
+characters exclusively (see below).\r
+\r
+Tab characters\r
+--------------\r
+The tab character must always be interpreted according to its\r
+traditional meaning:\r
+\r
+       Advance to the next column which is a multiple of 8.\r
+\r
+With this definition, even levels of indentation can be achieved with\r
+a sequence of tab characters, while odd levels of indentation may\r
+begin with a sequence of tab character but must end with 4 space\r
+characters.\r
+\r
+Some programmers have been misled by certain text editors into\r
+thinking that 4-space indentation can be achieved with tab characters\r
+exclusively by changing the meaning of tab character to be "advance to\r
+the next column which is a multiple of 4". Code formatted in this way,\r
+making an assumption of a fictitious 4-character-tab will not be\r
+accepted into cairo.\r
+\r
+The rationale here is that tabs are used in the code for lining things\r
+up other than indentation, (see the Whitespace section below), and\r
+changing the interpretation of tab from its traditional meaning will\r
+break this alignment.\r
+\r
+Braces\r
+------\r
+Most of the code in cairo uses bracing in the style of K&R:\r
+\r
+       if (condition) {\r
+           do_this ();\r
+           do_that ();\r
+       } else {\r
+           do_the_other ();\r
+       }\r
+\r
+but some of the code uses an alternate style:\r
+\r
+       if (condition)\r
+       {\r
+           do_this ();\r
+           do_that ();\r
+       }\r
+       else\r
+       {\r
+           do_the_other ();\r
+       }\r
+\r
+and that seems just fine. We won't lay down any strict rule on this\r
+point, (though there should be some local consistency). If you came\r
+here hoping to find some guidance, then use the first form above.\r
+\r
+If all of the substatements of an if statement are single statements,\r
+the optional braces should not usually appear:\r
+\r
+       if (condition)\r
+           do_this ();\r
+       else\r
+           do_that ();\r
+\r
+But the braces are mandatory when mixing single statement and compound\r
+statements in the various clauses. For example, do not do this:\r
+\r
+       if (condition) {\r
+           do_this ();\r
+           do_that ();\r
+       } else                  /* Yuck! */\r
+           do_the_other ();\r
+\r
+And of course, there are exceptions for when the code just looks\r
+better with the braces:\r
+\r
+       if (condition) {\r
+           /* Note that we have to be careful here. */\r
+           do_something_dangerous (with_care);\r
+       }\r
+\r
+       if (condition &&\r
+           other_condition &&\r
+           yet_another)\r
+       {\r
+           do_something ();\r
+       }\r
+\r
+And note that this last example also shows a situation in which the\r
+opening brace really needs to be on its own line. The following looks awful:\r
+\r
+       if (condition &&\r
+           other_condition &&\r
+           yet_another) {      /* Yuck! */\r
+           do_something ();\r
+       }\r
+\r
+As we said above, legible code that is easy to understand and maintain\r
+is the goal, not adherence to strict rules.\r
+\r
+Whitespace\r
+----------\r
+Separate logically distinct chunks with a single newline. This\r
+obviously applies between functions, but also applies within a\r
+function or block and can even be used to good effect within a\r
+structure definition:\r
+\r
+       struct _cairo_gstate {\r
+           cairo_operator_t op;\r
+\r
+           double tolerance;\r
+\r
+           /* stroke style */\r
+           double line_width;\r
+           cairo_line_cap_t line_cap;\r
+           cairo_line_join_t line_join;\r
+           double miter_limit;\r
+\r
+           cairo_fill_rule_t fill_rule;\r
+\r
+           double *dash;\r
+           int num_dashes;\r
+           double dash_offset;\r
+\r
+           ...\r
+       }\r
+\r
+Use a single space before a left parenthesis, except where the\r
+standard will not allow it, (eg. when defining a parameterized macro).\r
+\r
+Don't eliminate newlines just because things would still fit on one\r
+line. This breaks the expected visual structure of the code making it\r
+much harder to read and understand:\r
+\r
+       if (condition) foo (); else bar ();     /* Yuck! */\r
+\r
+Do eliminate trailing whitespace (space or tab characters) on any\r
+line. Also, avoid putting initial or final blank lines into any file,\r
+and never use multiple blank lines instead of a single blank line.\r
+\r
+Do enable the default git pre-commit hook that detect trailing\r
+whitespace for you and help you to avoid corrupting cairo's tree with\r
+it. Do that as follows:\r
+\r
+       chmod a+x .git/hooks/pre-commit\r
+\r
+You might also find the git-stripspace utility helpful which acts as a\r
+filter to remove trailing whitespace as well as initial, final, and\r
+duplicate blank lines.\r
+\r
+As a special case of the bracing and whitespace guidelines, function\r
+definitions should always take the following form:\r
+\r
+       void\r
+       my_function (argument)\r
+       {\r
+           do_my_things ();\r
+       }\r
+\r
+And function prototypes should similarly have the return type (and\r
+associated specifiers and qualifiers) on a line above the function, so\r
+that the function name is flush left.\r
+\r
+Break up long lines (> ~80 characters) and use whitespace to align\r
+things nicely. For example the arguments in a long list to a function\r
+call should all be aligned with each other:\r
+\r
+       align_function_arguments (argument_the_first,\r
+                                 argument_the_second,\r
+                                 argument_the_third);\r
+\r
+And as a special rule, in a function prototype, (as well as in the\r
+definition), whitespace should be inserted between the parameter types\r
+and names so that the names are aligned:\r
+\r
+       void\r
+       align_parameter_names_in_prototypes (const char *char_star_arg,\r
+                                            int         int_arg,\r
+                                            double     *double_star_arg,\r
+                                            double      double_arg);\r
+\r
+Note that parameters with a * prefix are aligned one character to the\r
+left so that the actual names are aligned.\r
+\r
+Managing nested blocks\r
+----------------------\r
+Long blocks that are deeply nested make the code very hard to\r
+read. Fortunately such blocks often indicate logically distinct chunks\r
+of functionality that are begging to be split into their own\r
+functions. Please listen to the blocks when they beg.\r
+\r
+In other cases, gratuitous nesting comes about because the primary\r
+functionality gets buried in a nested block rather than living at the\r
+primary level where it belongs. Consider the following:\r
+\r
+       foo = malloc (sizeof (foo_t));\r
+       if (foo) {                                      /* Yuck! */\r
+           ...\r
+           /* lots of code to initialize foo */\r
+           ...\r
+           return SUCCESS;\r
+       }\r
+       return FAILURE;\r
+\r
+This kind of gratuitous nesting can be avoided by following a pattern\r
+of handling exceptional cases early and returning:\r
+\r
+       foo = malloc (sizeof (foo_t));\r
+       if (foo == NULL)\r
+           return FAILURE;\r
+\r
+       ...\r
+       /* lots of code to initialize foo */\r
+       ...\r
+       return SUCCESS;\r
+\r
+The return statement is often the best thing to use in a pattern like\r
+this. If it's not available due to additional nesting above which\r
+require some cleanup after the current block, then consider splitting\r
+the current block into a new function before using goto.\r
+\r
+Memory allocation\r
+-----------------\r
+\r
+Because much of cairo's data consists of dynamically allocated arrays,\r
+it's very easy to introduce integer overflow issues whenever malloc()\r
+is called.  Use the _cairo_malloc2(), _cairo_malloc3(), and\r
+_cairo_malloc2_add1 macros to avoid these cases; these macros check\r
+for overflow and will return NULL in that case.\r
+\r
+  malloc (n * size) => _cairo_malloc_ab (n, size)\r
+    e.g. malloc (num_elts * sizeof(some_type)) =>\r
+         _cairo_malloc2 (num_elts, sizeof(some_type))\r
+\r
+  malloc (a * b * size) => _cairo_malloc_abc (a, b, size)\r
+    e.g. malloc (width * height * 4) =>\r
+         _cairo_malloc3 (width, height, 4)\r
+\r
+  malloc (n * size + k) => _cairo_malloc_ab_plus_c (n, size, k)\r
+    e.g. malloc (num * sizeof(entry) + sizeof(header)) =>\r
+         _cairo_malloc2k (num, sizeof(entry), sizeof(header))\r
+\r
+In general, be wary of performing any arithmetic operations in an\r
+argument to malloc.  You should explicitly check for integer overflow\r
+yourself in any more complex situations.\r
+\r
+Mode lines\r
+----------\r
+\r
+So given the rules above, what is the best way to simplify one's life as\r
+a code monkey? Get your editor to do most of the tedious work of\r
+beautifying your code!\r
+\r
+As a reward for reading this far, here are some mode lines for the more\r
+popular editors:\r
+/*\r
+ * vim:sw=4:sts=4:ts=8:tw=78:fo=tcroq:cindent:cino=\:0,(0\r
+ * vim:isk=a-z,A-Z,48-57,_,.,-,>\r
+ */\r
+\r
+\r
+TODO\r
+----\r
+\r
+Write rules for common editors to use this style.  Also cleanup/unify\r
+the modelines in the source files.\r
-- \r
1.6.6\r
\r