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

[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.
> > 
> > Comments?
> > I'd like to get this decided today or tomorrow so we know where we need
> > line breaks in Stefan Tauner's new struct flashchip patch.
> 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.

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.

> 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.

> 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.
 - 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.

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

Regards,
  Michael Karcher