Messages in this thread | | | Date | Thu, 8 Nov 2018 08:05:47 +0100 | From | Ingo Molnar <> | Subject | Re: [patch 2/2] Documentation/process: Add tip tree handbook |
| |
* 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
| |