Re: [PATCH v3] Add line-wrapping guidelines to the coding style documentation

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 14, 2007, 20:04 UTC
Message-ID: <7v4pfoh9vu.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <622166FD-0727-47D4-B26C-8A01788FD1EA@wincent.com>

Wincent Colaiuta <win@wincent.com> writes:

Show 11 quoted lines

> El 14/11/2007, a las 18:19, Johannes Schindelin escribió:
>
>> Besides, is it really necessary to be as explicit as you word it?
>> IOW is
>> this patch needed?
>
> I was basically just trying to help new people from making the same
> mistake that I did; ie. not knowing if there was an official limit,
> looking at the maximum line length in a file, making sure my patch
> didn't exceed that length (and re-wrapping to avoid exceeding it), and
> then getting reprimanded for gratuitous re-wrapping.

Sorry about that "reprimanded" part. I should have been more careful -- I did not really mean it that way. It was more like "it would have been nicer ... so please try to next time".

I know how stressful a life is for a contributor new to a project. You not only need to make sure the meat of your change is good, but worry about the technicalities, such as the presentation and style, the tone of the proposed log message that addresses other peoples efforts you are building on; in short, finding out the lay of the land, making yourself blend well in the comminity.

We have a great way to quickly tell if somebody is new to the project (i.e. "git shortlog --author=Wincent master"). I should use it more often and adjust my tone accordingly. It's only fair for me to do so when the new person surely is trying hard to do his part.

Show 14 quoted lines

> diff --git a/Documentation/CodingGuidelines b/Documentation/
> CodingGuidelines
> index 3b042db..d2d1f32 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -58,8 +58,6 @@ For C programs:
>   - We use tabs to indent, and interpret tabs as taking up to
>     8 spaces.
>
> - - We 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 code

I agree that "80 columns" sits better in that new "Line wrapping" section. I wonder if "tabs are 8 spaces wide" also belong there.

Show 15 quoted lines

> @@ -110,3 +108,14 @@ For C programs:
>     used in the git core command set (unless your command is clearly
>     separate from it, such as an importer to convert random-scm-X
>     repositories to git).
> +
> +Line wrapping:
> +
> + - We generally try to keep scripts, C source files and AsciiDoc
> +   documentation within the range of "80 columns minus some slop"
> +   to accommodate diff change marks [-+ ] and quoting ">> " in
> +   emails.
> +
> + - When submitting patches use common sense to decide whether to
> +   rewrap (or reindent), avoiding gratuitous changes.
> +