delta/git.git/Documentation/CodingGuidelines, branch jc/coding-guidelines

CodingGuidelines: clarify C #include rules

2015-01-15T23:42:50+00:00

Even though "advice.h" includes "git-compat-util.h", it is not
sensible to have it as the first #include and indirectly satisify
the "You must give git-compat-util.h a clean environment to set up
feature test macros before including any of the system headers are
included", which is the real requirement.

Because:

 - A command that interacts with the object store, config subsystem,
   the index, or the working tree cannot do anything without using
   what is declared in "cache.h";

 - A built-in command must be declared in "builtin.h", so anything
   in builtin/*.c must include it;

 - These two headers both include "git-compat-util.h" as the first
   thing; and

 - Almost all our *.c files (outside compat/ and borrowed files in
   xdiff/) need some Git-ness from "cache.h" to do something
   Git-ish.

let's explicitly specify that one of these three header files must
be the first thing that is included.

Any of our *.c file should include the header file that directly
declares what it uses, instead of relying on the fact that some *.h
file it includes happens to include another *.h file that declares
the necessary function or type.  Spell it out as another guideline
item.

Helped-by: Jeff King 
Signed-off-by: Junio C Hamano

CodingGuidelines: avoid "test -a/-o "

2014-05-20T18:19:43+00:00

The construct is error-prone; "test" being built-in in most modern
shells, the reason to avoid "test  && test " spawning
one extra process by using a single "test  -a " no
longer exists.

Signed-off-by: Junio C Hamano

CodingGuidelines: on splitting a long line

2014-05-02T21:08:16+00:00

Signed-off-by: Junio C Hamano

CodingGuidelines: on comparison

2014-05-02T20:44:46+00:00

There are arguments for writing a conditional as "a < b" rather than
"b > a", or vice versa.  Let's give guidance on which we prefer.

See http://thread.gmane.org/gmane.comp.version-control.git/3903/focus=4126
for the original discussion.

Signed-off-by: Junio C Hamano

CodingGuidelines: do not call the conditional statement "if()"

2014-05-02T20:26:07+00:00

The point immediately before it is about having SP after the control
keyword.  Spell it out as 'an "if" statement' instead.

Signed-off-by: Junio C Hamano

CodingGuidelines: give an example for shell function preamble

2014-05-02T20:24:57+00:00

Signed-off-by: Junio C Hamano

CodingGuidelines: give an example for control statements

2014-05-02T20:24:57+00:00

Signed-off-by: Junio C Hamano

CodingGuidelines: give an example for redirection

2014-05-02T20:24:57+00:00

Signed-off-by: Junio C Hamano

CodingGuidelines: give an example for case/esac statement

2014-05-02T20:24:57+00:00

Signed-off-by: Junio C Hamano

CodingGuidelines: once it is in, it is not worth the code churn

2014-05-02T20:24:57+00:00

Signed-off-by: Junio C Hamano