Even if our code is quite a good documentation for our coding style,
some people seem to prefer a document describing it.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
---
I long resisted in adding this, as I really believe our code
base is a very clean one, and a good description of what we
prefer.
But it seems that not everybody has the time to study our
code in depth, beautiful as it is ;-)
BTW the first to catch the allusion to a certain movie
wins a drink with me.
Documentation/CodingStyle | 87 +++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 87 insertions(+), 0 deletions(-)
create mode 100644 Documentation/CodingStyle
diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle
new file mode 100644
index 0000000..622b80b
--- /dev/null
+++ b/Documentation/CodingStyle
@@ -0,0 +1,87 @@
+As a popular project, we also have some guidelines to keep to the
+code. For git in general, two rough rules are:
+
+ - Most importantly, we never say "It's in POSIX; we'll happily
+ screw your system that does not conform." We live in the
+ real world.
+
+ - However, we often say "Let's stay away from that construct,
+ it's not even in POSIX".
+
+As for more concrete guidelines, just imitate the existing code
+(this is a good guideline, no matter which project you are contributing
+to...). But if you must have some list of rules, here they are.
+
+For shell scripts specifically (not exhaustive):
+
+ - We prefer $( ... ) for command substitution; unlike ``, it
+ properly nests. It should have been the way Bourne spelled
+ it from day one, but unfortunately isn't.
+
+ - We use ${parameter-word} and its [-=?+] siblings, and their
+ colon'ed "unset or null" form.
+
+ - We use ${parameter#word} and its [#%] siblings, and their
+ doubled "longest matching" form.
+
+ - We use Arithmetic Expansion $(( ... )).
+
+ - No "Substring Expansion" ${parameter:offset:length}.
+
+ - No shell arrays.
+
+ - No strlen ${#parameter}.
+
+ - No regexp ${parameter/pattern/string}.
+
+ - We do not use Process Substitution <(list) or >(list).
+
+ - We prefer "test" over "[ ... ]".
+
+ - We do not write noiseword "function" in front of shell
+ functions.
+
+For C programs:
+
+ - Use tabs to increment, and interpret tabs as taking up to 8 spaces
+
+ - Try to keep to 80 characters per line
+
+ - When declaring pointers, the star sides with the variable name, i.e.
+ "char *string", not "char* string" or "char * string". This makes
+ it easier to understand "char *string, c;"
+
+ - Do not use curly brackets unnecessarily. I.e.
+
+ if (bla) {
+ x = 1;
+ }
+
+ is frowned upon. A gray area is when the statement extends over a
+ few lines, and/or you have a lengthy comment atop of it.
+
+ - Try to make your code understandable. You may put comments in, but
+ comments invariably tend to stale out when the code they were
+ describing changes. Often splitting a function into two makes the
+ intention of the code much clearer.
+
+ Double negation is often harder to understand than no negation at
+ all.
+
+ Some clever tricks, like using the !! operator with arithmetic
+ constructs, can be extremely confusing to others. Avoid them,
+ unless there is a compelling reason to use them.
+
+ - Use the API. No, really. We have a strbuf (variable length string),
+ several arrays with the ALLOC_GROW() macro, a path_list for sorted
+ string lists, a hash map (mapping struct objects) named
+ "struct decorate", amongst other things.
+
+ - #include system headers in git-compat-util.h. Some headers on some
+ systems show subtle breakages when you change the order, so it is
+ best to keep them in one place.
+
+ - if you are planning a new command, consider writing it in shell or
+ perl first, so that changes in semantics can be easily changed and
+ discussed. Many git commands started out like that, and a few are
+ still scripts.
--
1.5.3.5.1597.g7191
-
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
