Re: [PATCH] Add Documentation/CodingStyle

[Johannes Schindelin <Johannes.Schindelin@gmx.de>]

Hi,

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

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> 
> > 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.

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

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

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

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