Re: [patch 2/2] Documentation/process: Add tip tree handbook

Ingo Molnar
2018-11-08T07:05:55Z

* Thomas Gleixner <tglx@linutronix.de> wrote:

> +Coding style notes
> +------------------
> +
> +Comment style
> +^^^^^^^^^^^^^
> +
> +Sentences in comments start with a uppercase letter.
> +
> +Single line comments::
> +
> + /* This is a single line comment */
> +
> +Multi-line comments::
> +
> + /*
> + * This is a properly formatted
> + * multi-line comment.
> + *
> + * Larger multi-line comments should be split into paragraphs.
> + */
> +
> +No tail comments:
> +
> + Please refrain from using tail comments. Tail comments disturb the
> + reading flow in almost all contexts, but especially in code::
> +
> + if (somecondition_is_true) /* Don't put a comment here */
> + dostuff(); /* Neither here */
> +
> + seed = MAGIC_CONSTANT; /* Nor here */
> +
> + Use freestanding comments instead::
> +
> + /* This condition is not obvious without a comment */
> + if (somecondition_is_true) {
> + /* This really needs to be documented */
> + dostuff();
> + }
> +
> + /* This magic initialization needs a comment. Maybe not? */
> + seed = MAGIC_CONSTANT;

Yeah, so I think a better way to visualize and explain the 'no tail
comments' guideline in -tip is not these more complex code flows, but the
totally simple linear flows of statements.

With tail comments the code looks like this:

res = dostuff(); /* We explain something here. */

seed = 1; /* Another explanation. */

mod_timer(&our_object->our_timer, jiffies + OUR_INTERVAL); /* We like to talk */

res = check_stuff(our_object); /* We explain something here. */
if (res)
return -EINVAL;

interval = nontrivial_calculation(); /* Another explanation. */

mod_timer(&our_object->our_timer, jiffies + interval); /* This doesn't race, because. */

... while with freestanding comments it's:

/* We explain something here: */
res = check_stuff(our_object);
if (res)
return -EINVAL;

/* Another explanation: */
interval = nontrivial_calculation();

/* This doesn't race with init_our_stuff(), because: */
mod_timer(&our_object->our_timer, jiffies + interval);

This comment placement style has several advantages:

- Comments precede actual code - while in tail comments it's exactly
the wrong way around.

- We don't create over-long lines nor artificially short tail comments
just because we were trying to stay within the col80 limit with the
"this doesn't race" comment. The full-line comment was able to
explain that the race is with init_our_stuff().

- Freestanding oneliner comments are much better aligned as well: note
how ever comment starts at the exact same column, making it very easy
to read (or not to read) these comments.

- In short: predictable visual parsing rules and proper semantic
ordering of information is good, random joining of typographical
elements just to create marginally more compact source code is bad.

- Just *look* at the tail comments example: it's a visually diffuse,
jumble of statements and misaligned comments with good structure.

Do you want me to send a delta patch, or an edited document?

Thanks,

Ingo