From: Junio C Hamano <gitster@pobox.com>
To: Johannes Schindelin <Johannes.Schindelin@gmx.de>
Cc: Robin Rosenberg <robin.rosenberg.lists@dewire.com>,
Andreas Ericsson <ae@op5.se>,
Ralf Wildenhues <Ralf.Wildenhues@gmx.de>,
git@vger.kernel.org
Subject: Re: [PATCH v3] Add Documentation/CodingGuidelines
Date: Wed, 07 Nov 2007 15:14:17 -0800 [thread overview]
Message-ID: <7vtznx8x86.fsf@gitster.siamese.dyndns.org> (raw)
In-Reply-To: <Pine.LNX.4.64.0711072233010.4362@racer.site> (Johannes Schindelin's message of "Wed, 7 Nov 2007 22:35:33 +0000 (GMT)")
Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> new file mode 100644
> index 0000000..2d8656f
> --- /dev/null
> +++ b/Documentation/CodingGuidelines
> @@ -0,0 +1,106 @@
> +As a popular project, we also have some guidelines to keep to the
> +code. For git in general, two rough rules are:
I'd rather not to say "As a popular project" here. That is
something for others to decide, not for us to advertise.
Also we now have three rules here ;-).
> +
> + - Most importantly, we never say "It's in POSIX; we'll happily
> + ignore your needs should your system that does not conform."
"should your system not conform"? "if your system does not
conform"?
> +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.
s/\.\.\.//;
> +For C programs:
> +
> + - Use tabs to indent, and interpret tabs as taking up to 8 spaces
> +
> + - Try to keep to at most 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;"
End each sentence with a full stop "." for consistency.
> +
> + - 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. Also,
> + like in the Linux kernel, if there is a long list of "else if"
> + statements, it can make sense to add curly brackets to single
> + line blocks.
As Robin suggests, s/Do not use/Avoid using/ feels more in line
with the spirit with the "A gray area is..." description.
I think the official name for {} are "braces", by the way.
> + 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.
Need a bullet point "-" before "Double" (but not "Some").
> + - #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.
> +
The first #include in C files except platform specific compat/
implementation should be git-compat-util.h or another header
file that includes it, such as cache.h and builtin.h.
> + - 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.
Begin a statement with a Capital letter, for consistency.
next prev parent reply other threads:[~2007-11-07 23:14 UTC|newest]
Thread overview: 38+ messages / expand[flat|nested] mbox.gz Atom feed top
2007-11-06 20:15 [PATCH 0/5] some shell portability fixes Ralf Wildenhues
2007-11-06 20:17 ` [PATCH 1/5] Avoid a few unportable, needlessly nested "...`..." Ralf Wildenhues
2007-11-06 20:17 ` [PATCH 2/5] Fix sed script to work with AIX sed Ralf Wildenhues
2007-11-06 20:18 ` [PATCH 3/5] Replace $((...)) with expr invocations Ralf Wildenhues
2007-11-06 20:26 ` Ralf Wildenhues
2007-11-06 21:06 ` Junio C Hamano
2007-11-06 23:17 ` [PATCH] Add Documentation/CodingStyle Johannes Schindelin
2007-11-07 0:04 ` Andreas Ericsson
2007-11-07 0:40 ` Junio C Hamano
2007-11-07 8:52 ` Andreas Ericsson
2007-11-07 14:59 ` [PATCH v2] " Johannes Schindelin
2007-11-07 21:43 ` Robin Rosenberg
2007-11-07 22:35 ` [PATCH v3] Add Documentation/CodingGuidelines Johannes Schindelin
2007-11-07 23:14 ` Junio C Hamano [this message]
2007-11-08 0:33 ` [PATCH v4] " Johannes Schindelin
2007-11-08 0:38 ` Junio C Hamano
2007-11-07 14:54 ` [PATCH] Add Documentation/CodingStyle Johannes Schindelin
2007-11-07 7:53 ` Wincent Colaiuta
2007-11-07 8:53 ` Andreas Ericsson
2007-11-07 19:40 ` Jon Loeliger
2007-11-07 20:13 ` Johannes Schindelin
2007-11-08 11:29 ` Mike Ralphson
2007-11-06 20:20 ` [PATCH 4/5] Fix sed string regex escaping in module_name Ralf Wildenhues
2007-11-06 20:20 ` [PATCH 5/5] Avoid "test -o" and "test -a" which are not POSIX, only XSI Ralf Wildenhues
2007-11-06 20:46 ` [PATCH 0/5] some shell portability fixes Junio C Hamano
2007-11-06 21:02 ` Mike Hommey
2007-11-06 23:25 ` Johannes Schindelin
2007-11-07 14:17 ` Mike Ralphson
2007-11-07 14:47 ` Johannes Schindelin
2007-11-07 15:30 ` Mike Ralphson
2007-11-07 15:37 ` Johannes Schindelin
2007-11-06 21:09 ` Ralf Wildenhues
2007-11-07 15:58 ` Nguyen Thai Ngoc Duy
2007-11-07 16:05 ` Nguyen Thai Ngoc Duy
2007-11-07 20:42 ` Junio C Hamano
2007-11-08 6:14 ` Ralf Wildenhues
2007-11-12 11:20 ` Nguyen Thai Ngoc Duy
2007-11-10 22:30 ` Miles Bader
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7vtznx8x86.fsf@gitster.siamese.dyndns.org \
--to=gitster@pobox.com \
--cc=Johannes.Schindelin@gmx.de \
--cc=Ralf.Wildenhues@gmx.de \
--cc=ae@op5.se \
--cc=git@vger.kernel.org \
--cc=robin.rosenberg.lists@dewire.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).