From: Andreas Ericsson <ae@op5.se>
Date: Wed, 14 Nov 2007 19:08:48 GMT
Subject: Re: [PATCH v3] Add line-wrapping guidelines to the coding style documentation
Message-ID: <473B47C0.6030508@op5.se>
In-Reply-To: <622166FD-0727-47D4-B26C-8A01788FD1EA@wincent.com>

Wincent Colaiuta wrote:
> Help new contributors by providing some advice about line-wrapping; the
> advice basically boils down to "use 80 columns minus some slop as a
> rule of thumb", but also "use common sense", and "avoid gratuitous
> rewrapping".
> 
> Signed-off-by: Wincent Colaiuta <win@wincent.com>
> ---
> 
> El 14/11/2007, a las 18:19, Johannes Schindelin escribió:
> 
>> On Wed, 14 Nov 2007, Wincent Colaiuta wrote:
>>
>>> Help new contributors by providing some advice about line-wrapping; the
>>> advice basically boils down to "use 80-characters minus some slop as a
>>> rule of thumb", but also "use common sense", and "avoid gratuitous
>>> rewrapping".
>>
>> We already have this:
>>
>> - We try to keep to at most 80 characters per line.
> 
> Ah, didn't see that. It's in the "C programs" section and I was trying 
> to provide a guideline that applied to all source types (given that this 
> all started with a doc patch to an AsciiDoc source file).
> 
>> 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.
> 
> As for the explicitness, I was just paraphrasing the guidelines as Junio 
> expressed them.
> 
>> Because if we go down that road, we might very well end up with a
>> CodingGuidelines document that is larger than git's source code.
> 
> 134 lines down (the current length of CodingGuidelines with that patch), 
> about 100,000 lines to go (the rest of the codebase). So if we try very 
> hard, we could indeed get there.
> 
> Here follows a revised patch which is more concise, and keeps all 
> wrapping references at a single place. I lose your "at most 80 
> characters" in favor of Junio's "80-characters minus some slop", and in 
> fact state "80 columns" rather than "80 characters", because that's what 
> we're really talking about, isn't it?
> 
> Cheers,
> Wincent
> 
>  Documentation/CodingGuidelines |   13 +++++++++++--
>  1 files changed, 11 insertions(+), 2 deletions(-)
> 
> 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
> @@ -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

"We generally try to keep source and documentation" ... ?

-- 
Andreas Ericsson                   andreas.ericsson@op5.se
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231