* Thomas Gleixner <t...@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
