--- /dev/null
+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
projects / notmuch-archives.git / commitdiff