Re: [PATCH] Add Documentation/CodingStyle

Hi,

On Tue, 6 Nov 2007, Junio C Hamano wrote:

Johannes Schindelin [off-list ref] writes:

quoted

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".
+

I am not sure if we want to have CodingStyle document, but the
above are not CodingStyle issues.

Would you like to call it CodingConventions?

If we are to write this down, I'd like to have the more
important third rule, which is:

 - In spite of the above two rules, we sometimes say "Although
   this is not in POSIX, it (is so convenient | makes the code
   much more readable | has other good characteristics) and
   practically all the platforms we care about support it, so
   let's use it".  Again, we live in the real world, and it is
   sometimes a judgement call, decided based more on real world
   constraints people face than what the paper standard says.

Okay, will add.

quoted

+For C programs:
+
+ - Use tabs to increment, and interpret tabs as taking up to 8 spaces

What's the character for decrement?  DEL? ;-)

Hehe.  As you undoubtedly guessed, I meant "indent"...

quoted

+   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.

I actually think (!!var) idiom is already established in our
codebase.

Yep, but when there are easier variants, AFAICT they were preferred.

quoted

+ - 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.

 - When you come up with an API, document it.

Okay.

quoted

+ - 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.

No Python allowed?

Well, maybe we should allow that again.  Although I hoped we are over that 
now, as it would complicate the msysGit efforts tremendously.

Ciao,
Dscho