[RFC] Change coding style rule: 80 column "hard limit" for ChangeLogs

[RFC] Change coding style rule: 80 column "hard limit" for ChangeLogs

[Doug Evans]

We have so many style rules, IWBN to simplify things where possible.

Does anyone know the origin of the 74 column "hard" limit for ChangeLogs?

I propose we change that to 80 to match the rule for code:
one column limit for everything.

I'm referring to the "hard" limit here.  Apparently there's a 70-character
soft limit for code:

https://sourceware.org/gdb/wiki/JoelsCodingStyleCheatSheet#Maximum_line_length

Re: [RFC] Change coding style rule: 80 column "hard limit" for ChangeLogs

[Eli Zaretskii]

> From: Doug Evans <dje@google.com>
> Date: Fri, 03 Jan 2014 14:50:01 -0800
> 
> Does anyone know the origin of the 74 column "hard" limit for ChangeLogs?

AFAIK, that's because this is the default in Emacs's commands that
manipulate ChangeLog entries.  Here:

  (define-derived-mode change-log-mode text-mode "Change Log"
    "Major mode for editing change logs; like Indented Text mode.
  Prevents numeric backups and sets `left-margin' to 8 and `fill-column' to 74.
  New log entries are usually made with \\[add-change-log-entry] or \\[add-change-log-entry-other-window].
  Each entry behaves as a paragraph, and the entries for one day as a page.
  Runs `change-log-mode-hook'.
  \n\\{change-log-mode-map}"
    (setq left-margin 8
	  fill-column 74   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<
	  indent-tabs-mode t
	  tab-width 8
	  show-trailing-whitespace t)

Re: [RFC] Change coding style rule: 80 column "hard limit" for ChangeLogs

[Joel Brobecker]

> AFAIK, that's because this is the default in Emacs's commands that
> manipulate ChangeLog entries.  Here:
> 
>   (define-derived-mode change-log-mode text-mode "Change Log"
>     "Major mode for editing change logs; like Indented Text mode.
>   Prevents numeric backups and sets `left-margin' to 8 and `fill-column' to 74.
>   New log entries are usually made with \\[add-change-log-entry] or \\[add-change-log-entry-other-window].
>   Each entry behaves as a paragraph, and the entries for one day as a page.
>   Runs `change-log-mode-hook'.
>   \n\\{change-log-mode-map}"
>     (setq left-margin 8
> 	  fill-column 74   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<
> 	  indent-tabs-mode t
> 	  tab-width 8
> 	  show-trailing-whitespace t)

We can transparently override it, I think, since our ChangeLog entries have:

> Local Variables:
> mode: change-log
> left-margin: 8
> fill-column: 74
> version-control: never
> coding: utf-8
> End:

(to be confirmed, since I am no longer an emacs user).

That being said, and fwiw only, I subscribe to the idea that 80
characters is a little bit on the long side. I think it's a good
idea to have one limit, and one limit only, but I'd prefer to
make it closer to 70 than 80 - maybe 74 could be a good compromise.
Ie, raise the soft-limit for the code to 74, leave the hard-limit
to 80, and thus keep ChangeLogs as is.

Other than the opinion above, it's not really all that important to me.
So I'm good with whatever reasonable limit the group decides. We just
need to make sure we document the decision, with reference to the
discussion.

-- 
Joel

Re: [RFC] Change coding style rule: 80 column "hard limit" for ChangeLogs

[Doug Evans]

[apologies for the resend]

On Sat, Jan 4, 2014 at 8:00 PM, Joel Brobecker <brobecker@adacore.com> wrote:
>> AFAIK, that's because this is the default in Emacs's commands that
>> manipulate ChangeLog entries.  Here:
>>
>>   (define-derived-mode change-log-mode text-mode "Change Log"
>>     "Major mode for editing change logs; like Indented Text mode.
>>   Prevents numeric backups and sets `left-margin' to 8 and `fill-column' to 74.
>>   New log entries are usually made with \\[add-change-log-entry] or \\[add-change-log-entry-other-window].
>>   Each entry behaves as a paragraph, and the entries for one day as a page.
>>   Runs `change-log-mode-hook'.
>>   \n\\{change-log-mode-map}"
>>     (setq left-margin 8
>>         fill-column 74   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<
>>         indent-tabs-mode t
>>         tab-width 8
>>         show-trailing-whitespace t)
>
> We can transparently override it, I think, since our ChangeLog entries have:
>
>> Local Variables:
>> mode: change-log
>> left-margin: 8
>> fill-column: 74
>> version-control: never
>> coding: utf-8
>> End:
>
> (to be confirmed, since I am no longer an emacs user).
>
> That being said, and fwiw only, I subscribe to the idea that 80
> characters is a little bit on the long side. I think it's a good
> idea to have one limit, and one limit only, but I'd prefer to
> make it closer to 70 than 80 - maybe 74 could be a good compromise.
> Ie, raise the soft-limit for the code to 74, leave the hard-limit
> to 80, and thus keep ChangeLogs as is.

That would not achieve the goal of one limit only,
unless ChangeLogs have a hard limit of 80, and 74 is the soft limit.

[I'm treating "hard" as "do not violate unless there's a compelling reason",
and "soft" as a guideline. btw, I can no longer think of that word without also
thinking of Pirates of the Caribbean. :-)]

> Other than the opinion above, it's not really all that important to me.
> So I'm good with whatever reasonable limit the group decides. We just
> need to make sure we document the decision, with reference to the
> discussion.

I'm not overly fond of anything below 80 (well, 79, but I certainly
don't reject patches that use 80).

Vertical space usage is not unimportant, and comments like this:

  /* Some comment, ... mumble
      it.  */

bug me when there's more than enough space to use one fewer line.
But if it's just a soft limit, then at least I can avoid it in my own patches.

Re: [RFC] Change coding style rule: 80 column "hard limit" for ChangeLogs

[Joel Brobecker]

> That would not achieve the goal of one limit only,
> unless ChangeLogs have a hard limit of 80, and 74 is the soft limit.
> 
> [I'm treating "hard" as "do not violate unless there's a compelling reason",
> and "soft" as a guideline. btw, I can no longer think of that word without also
> thinking of Pirates of the Caribbean. :-)]
> 
> > Other than the opinion above, it's not really all that important to me.
> > So I'm good with whatever reasonable limit the group decides. We just
> > need to make sure we document the decision, with reference to the
> > discussion.
> 
> I'm not overly fond of anything below 80 (well, 79, but I certainly
> don't reject patches that use 80).

I'm really easy, so I don't mind your proposal.

Just for the record, to me, "soft" means "stay within the limit unless
you have a reasonable reason to exceed", while "hard" means "do not
exceed unless you just cannot do otherwise". As you can see, slightly
stronger barriers. But I know also that it's really nitpicking, so
I tend to worry too much about soft violations when reviewing patches,
making that soft barrier a little softer :-). But I pay attention to
that limit myself when modifying the code.

-- 
Joel

Re: [RFC] Change coding style rule: 80 column "hard limit" for ChangeLogs

[Doug Evans]

On Wed, Jan 8, 2014 at 3:45 AM, Joel Brobecker <brobecker@adacore.com> wrote:
>> That would not achieve the goal of one limit only,
>> unless ChangeLogs have a hard limit of 80, and 74 is the soft limit.
>>
>> [I'm treating "hard" as "do not violate unless there's a compelling reason",
>> and "soft" as a guideline. btw, I can no longer think of that word without also
>> thinking of Pirates of the Caribbean. :-)]
>>
>> > Other than the opinion above, it's not really all that important to me.
>> > So I'm good with whatever reasonable limit the group decides. We just
>> > need to make sure we document the decision, with reference to the
>> > discussion.
>>
>> I'm not overly fond of anything below 80 (well, 79, but I certainly
>> don't reject patches that use 80).
>
> I'm really easy, so I don't mind your proposal.
>
> Just for the record, to me, "soft" means "stay within the limit unless
> you have a reasonable reason to exceed", while "hard" means "do not
> exceed unless you just cannot do otherwise". As you can see, slightly
> stronger barriers. But I know also that it's really nitpicking, so
> I tend to worry too much about soft violations when reviewing patches,
> making that soft barrier a little softer :-). But I pay attention to
> that limit myself when modifying the code.

So how about a 74 soft limit and 80 hard limit for everything (modulo
things like .exp files where we try to keep things under 80 but  some
lines are just long and best left as is).

soft = "stay within the limit unless you have a reasonable reason to
exceed, and we're not nitpicky on what reasonable is"

hard = "do not exceed unless you just cannot do otherwise, and while
there are exceptions, we are quite nitpicky on this one"

Even that wording doesn't preclude different interpretations.  I'm
happy to tweak it.  The high order bits for me are the same numbers
for everything, and not being nitpicky on adherence to the soft limit.

If there are no objections, I will tweak your coding style cheat sheet
wiki (just trying to save you the trouble, it's your page, feel free
to edit as desired), and update other docs (the CodingStandards wiki
doesn't exist, I'll create it and add something to get it going).

Re: [RFC] Change coding style rule: 80 column "hard limit" for ChangeLogs

[Sergio Durigan Junior]

On Wednesday, January 08 2014, Doug Evans wrote:

> So how about a 74 soft limit and 80 hard limit for everything (modulo
> things like .exp files where we try to keep things under 80 but  some
> lines are just long and best left as is).

I'm following the discussion, and I'm happier with this rule.

FWIW, I try to keep things under 76 chars, but that's only my personal
rule :-).

-- 
Sergio

Re: [RFC] Change coding style rule: 80 column "hard limit" for ChangeLogs

[Joel Brobecker]

> So how about a 74 soft limit and 80 hard limit for everything (modulo
> things like .exp files where we try to keep things under 80 but  some
> lines are just long and best left as is).
> 
> soft = "stay within the limit unless you have a reasonable reason to
> exceed, and we're not nitpicky on what reasonable is"
> 
> hard = "do not exceed unless you just cannot do otherwise, and while
> there are exceptions, we are quite nitpicky on this one"
> 
> Even that wording doesn't preclude different interpretations.  I'm
> happy to tweak it.  The high order bits for me are the same numbers
> for everything, and not being nitpicky on adherence to the soft limit.

I all works for me.

> If there are no objections, I will tweak your coding style cheat sheet
> wiki (just trying to save you the trouble, it's your page, feel free
> to edit as desired), and update other docs (the CodingStandards wiki
> doesn't exist, I'll create it and add something to get it going).

I don't consider it my property so feel free to edit and improve as
you see fit. The purpose is to have something as useful as possible
to others, and also as a way to keep track of past discussions that
lead to the various rules (hence HTML instead of texi). I initially
created it and put my name next to it to make it extra clear that
it's unofficial and WIP.

Now that gdbint has been moved to the wiki, I should probably think
of merging this with the rest of gdbinit at some point.

Thanks!
-- 
Joel