[flashrom] 80/100/132 column line width policy

[Carl-Daniel Hailfinger]

Am 12.03.2012 22:23 schrieb Michael Karcher:
> Am Sonntag, den 11.03.2012, 23:00 +0100 schrieb Stefan Tauner:
>>> Keeping the old 80 column limit is not really an option anymore.
>>> Standard terminal sizes have one of 80, 100 or 132 columns.
>>> Given the monitor resolutions many people have nowadays, I think it is
>>> safe to say that you can fit two xterms with 100 columns horizonally
>>> next to each other. 100 columns should also be sufficient for a msg_p*
>>> of roughly 80 columns of text.
>>> 132 columns provide more leeway, but IMHO that would be too wide for
>>> good readability (and my screen can't fit two xterms side-by-side anymore).
>>>
>>> Of course some files have sections where any column limit is not
>>> acceptable (board lists etc.), but the column limit violations should be
>>> limited to the affected file sections, not whole files.
>> i would prefer more complex rules than a simple "break the line at a
>> maximum of n chars or die".
>> increasing the hard limit would lower the frequency for anger-inducing
>> line breaks on my side a bit, but won't solve the problem completely.
> The idea of line length limits is of course not to make anyone angry,
> but to make the code readable in a "typical" editing situation. Even if
> my window is just one or two characters too small, the last character
> gets chopped off at the right margin of the window. So there is a kind
> of hard limit for the person trying to read the code. But as windows can
> be resized, the limit is still kind-of soft. Defining some "window size
> that makes you able to see all the code" still would be a good idea to
> prevent a slow creep of steadily increasing line lenghts (like "Hey,
> it's just one char longer than this other line, so why is this line
> forbidden?!")
>
> Also having strings in the source as they are printed is a good idea, so
> we need at least 2*tabsize + strlen("msg_perr(\"") + strlen("\");") = 29
> more chars than 80 characters (actually, for adding a "\n", even a bit
> more, but you seldomly hit the 80 exactly, so to have messages in a once
> indented block in a function body, you need 110 chars.

My screen can fit two xterms with exactly 112 columns each next to each
other, so I like this suggestion.


> On the other hand, the estimate of 200 chars/screen is quite reasonable
> for 4:3 monitors (which are still in use by a lot of programmers), so
> 100 chars to put to terminals next to each other sound sensible, too.

100 columns is of course nice as well.


>> i think i once proposed something like the following after you went
>> offline, so i am repeating it now in an RFC.
>>
>> x chars soft limit (e.g. 90);
>> y chars hard limit (e.g. 120);
>> o chars overhang (< 5 or "common sense").
>>
>> before reaching x one should try to break at a convenient spot like
>> logical operators for multi-term conditions, parameter names etc just
>> like one usually does before hard limits.
>> most printed text strings should have their line breaks before x at
>> usual indention depths ((1 to 3)*8).
>> expressions that fit in y chars completely, but not in x should *not* be
>> split.
> This means I need to have the window y chars wide to be able to read the
> expression. So the soft limit of x does not really help. Thus I don't
> get what the advantage of a soft limit so much lower than the hard limit
> is useful for.
>
>> optional: expressions that fit in y + o chars, should not be split,
>> just for the sake of obeying the limit i.e. if it would make the
>> expression less readable (e.g. the case where ";" breaks the limit and
>> i start swearing :P)
> And here you are kind-of re-inventing the soft-limit/hard-limit split,
> but this time with a 5 char difference instead of a 30 char difference.
> If the stuff that is not fitting my window is just a semicolon after a
> function call with unused result, you can be quite sure that what is
> "lost" is just a semicolon. For a printing function, even if the window
> is just up to the closing quote, the closing parenthesis and the
> semicolon need not be visible to understand the line.
> So a small overhang indeed makes sense, if you consider it as: "If I
> don't see the characters in the overhang, can I still be quite confident
> I know what the code does?" If you can answer that question with yes,
> use the overhang.

And I'm totally against having 4 kinds of limits: extremely soft
(Stefan's soft limit), soft (Stefan's hard limit), hard (Stefan's
hard+overhang) and none (for tables).
The no-limits exception for tables is good. No objection there.
Everybody is free to introduce linebreaks before any limit if it
improves readability. Admittedly those linebreaks will disappear if
someone runs indent on the code and commits it as "trivial patch" - we
had quite a few such commits in the past (and I was not really happy
about that).
Other than for tables, I really want a hard limit with no exceptions
because I'm pretty sure there will be quite some disagreement about what
constitutes being "confident about what the code does". For me, "\n" or
not is a question which has an impact on output, especially when I'm
hunting for empty lines which got printed somewhere. Even more so if
we're talking about parts of a printed string which contain format
strings. If I have to resize the terminal anyway to see the complete
code, I might as well make the most of it and not waste lines by
introducing linebreaks elsewhere.


>> optional #2: neither limit should apply to printed text strings. they
>> should be broken at "\n" no matter how far that is. the rationale is
>> that it is possible to see if they are sanely formatted without runtime
>> tests.
> Makes sense too, if you require that the varargs for a printf-like
> function again are fitting the limit. Having to scroll the window to
> read a detailed message is fine with me, as long as everything except
> string constants is completely understandable without scrolling.
>
>> here, but i think i can cope better with "annoying" preferences of
>> others when reviewing patches or getting feedback than with hard limits
>> that make me write lines like "\tab\tab\tab  i) {". :)
> Kind-of far-fetched example. Usually you should have a better line break
> point before that. Only exception where this might not be the case is:
>    msg_pinfo("%d frobbing fizzles of furious foxes failed. Try teasing turkeys to\n"
>              "testify the truth. Ignoring irratating ibises is immensely important\n", i);
> In this case, the only sensible line-break point really *is* before the
> i. As an occasional reader of that code, I might not be interested
> whether teasing turkeys or teasing tortoises is suggested, but I am more
> likely interested in knowing what value is printed. If the "i" gets
> pushed out of the window, I loose important information. So, yes, in
> this case, I am all for having "\tab\tab\tab i);" on a line. The comma
> may disappear past the right-border, as that comma is obviously there if
> the code compiles.
>
> So my 2 cents for the discussion is:
>  - we should have a "suggested window size" (kind of equals your hard
> limit.
>  - only "obvious" characters may be past that window size
>  - verbose hints (where flashrom tries to write novels to the screen)
>    are unaffected of the suggested window size, but the output needs to
>    fit in 80 chars.
> with following softeninig applied
>  - If some section of code is way more legible if you get some extra
>    chars, take them. not being able to read a code side-by-side without
>    horizontal scrolling of the window is the lesser evil compared to
>    having lots of obnoxious line breaks.
>  - BUT: Do not assume if you exceeded this limit by 3 chars according
>    to the previous rule this is generally the new suggested window size!
>  - Plain string constants may exceed the suggested window size in the
>    "flashrom writes a novel" case. If the message itself is not
>    multi-line, but just on one line, break it, if you have to break
>    the line anyway for the printf varargs.

And what line length would be the real hard (no exceptions except for
tables) limit? The softening of limits just makes it harder to find out
what the real limit is, and I don't think there is any indentation tool
(even the stuff which is not as crappy as GNU indent) which has enough
atificial intelligence to find out what's considered to be "obvious"
content allowed after the limit.


>  - Use whatever space you need for tables, but don't make them wider
>    than necessary.
>
> For the last item about making tables not wider than necessary I suggest
> to not use TABs inside a table, but *only* for indention of code blocks.
> This enables changing the tab size without everything falling apart -
> you just get a different indent steps. The consequence for tables is
> that if some column is determined to take 11 characters (including comma
> and space), you can just use them instead of needing to use 16
> characters to get back to the TAB grid.
> If in a table one column entry is excessively long (e.g. a board name
> like "P9XGH3-Deluxe/Pro or P9XGH4-basic", this does not necessarily mean
> this excessive entry determines column width. Especially if it is
> followed by filler entries like NULL or 0 which can be squashed below
> nominal column width, so interesting fields do again line up.

Full agreement for squeezing tables in a way which does not make a table
the vitcim of its longest member.

> For the "suggested window size, I think carldani's value 100 would be a
> good start.

Regards,
Carl-Daniel

-- 
http://www.hailfinger.org/