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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Thu, 8 Nov 2018 08:05:47 +0100
From:   Ingo Molnar <mingo@...nel.org>
To:     Thomas Gleixner <tglx@...utronix.de>
Cc:     LKML <linux-kernel@...r.kernel.org>, x86@...nel.org,
        Peter Zijlstra <peterz@...radead.org>,
        Paul McKenney <paulmck@...ux.vnet.ibm.com>,
        John Stultz <john.stultz@...aro.org>,
        Arnaldo Carvalho de Melo <acme@...hat.com>,
        Frederic Weisbecker <frederic@...nel.org>,
        Jonathan Corbet <corbet@....net>,
        Andy Lutomirski <luto@...nel.org>,
        Marc Zyngier <marc.zyngier@....com>,
        Daniel Lezcano <daniel.lezcano@...aro.org>,
        Dave Hansen <dave.hansen@...ux.intel.com>,
        Ard Biesheuvel <ard.biesheuvel@...aro.org>,
        Will Deacon <will.deacon@....com>,
        Mark Brown <broonie@...nel.org>,
        Dan Williams <dan.j.williams@...el.com>
Subject: Re: [patch 2/2] Documentation/process: Add tip tree handbook


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