Re: Thoughts on doxygen for internal documentation

[Daniel Berlin <dberlin at dberlin dot org>]

On Thu, 16 Jan 2003, Daniel Egger wrote:

> Am Don, 2003-01-16 um 19.03 schrieb Theodore Papadopoulo:
>
> > As an example, I always wondered why the rule of 80 columns is still
> > that strict. IMHO often code can be more readable using longer lines
> > (still with a reasonnable limit, just an higher one).  Yes I know, some
> > people still have a very old 80 columns VT100, but those cannot be
> > that many ? Indeed, mail reader sometimes have this 80 limit constraints,
> > but then problems with line wrapping by mailers happen also with 80
> > columns... So why keeping this constraints and not updating it to
> > something more sensible such as eg 132 colums.
>
> I really doubt that having more characters per line increases
> readability, rather I claim *really* needing that much space means
> that someone is doing something outright stupid and not well-thought,
> sometimes because he/she/it simply doesn't know better, but forcing
> her/him/it to break the line also enforces reconsidering the source
> sometimes leading to easier and/or more effective code.

Not necessarily.
There are some pretty long macro names in gcc.

Let's take, for instance, on the rtlopt-branch, the VAR_LOCATION notes.

To compare two of the locations in them will take
if (rtx_equal_p (NOTE_VAR_LOCATION_LOC (var1), NOTE_VAR_LOCATION_LOC (var2))

That's 77 characters.  Imagine what happens if you are storing these notes
in some other structure. You basically have to store them to temporary,
just so one can read the code.
But it *really* needs that much space to do something non-stupid, and well
thought out.
You can't come up with a better name (NOTE_VAR_LOC_LOC would be a bit
confusing, and they are notes describing variable locations, so what else
would you call them).
You can't change the fact that we have to store them, etc.

Not that this line shouldn't be split, i'm just disputing that anything
really needing that much space is somehow bad code.
I also don't think that storing things to temporaries with shorter
names just so the line looks nicer is "more effective" code, just nicer
looking code.
But that's what one ends up doing a lot.
Especially when you end up with C that wants to do a lot of what C++ does,
so you have tons of macros or accessor functions that you could use a
shorter name for in C++ (IE in member functions), but can't in C.

 >
> No, my terminal is not limited to 80 characters though I appreciate
> that measure because I can fit exactly 4 80x25 in X on my screen. :)
>
> --
> Servus,
>        Daniel
>