LKML Archive on lore.kernel.org
 help / color / Atom feed
From: Linus Torvalds <torvalds@transmeta.com>
To: Mark I Manning IV <mark4@purplecoder.com>
Cc: Kernel Mailing List <linux-kernel@vger.kernel.org>
Subject: Re: Coding Style
Date: Fri, 19 Jan 2001 22:29:35 -0800 (PST)
Message-ID: <Pine.LNX.4.10.10101192217390.9361-100000@penguin.transmeta.com> (raw)
In-Reply-To: <3A68E309.2540A5E1@purplecoder.com>



On Fri, 19 Jan 2001, Mark I Manning IV wrote:
> 
> Two spaces are perfect, they delineate the blocks very nicely and dont
> eat up the comments real estate.

WHAT "comments real estate". You have tons of real estate - up and down.
Don't try to move it sideways where it won't fit anyway.

Write comments before your function. If your function is so long and
complicated that you think it needs comments after the lines, then you
should have split it up. See "function growth hormone imbalance".

> > And two spaces is not enough. If you write code that needs comments at
> > the end of a line, your code is crap.
> 
> Might i ask you to qualify that statement ?

Ok. I'll qualify it. Add a "unless you write in assembly language" to the
end. I have to admit that most assembly languages are terse and hard to
read enough that you often want to comment at the end. In assembly you
just don't tend to have enough flexibility to make the code readable, so
you must live with unreadable code that is commented.

> I disagree, comments should be associated with the code they are
> describing, putting a block of comments before a function telling people
> waht it does does nothign to tell them HOW it does it.  

Just add a "how it does it" section to your comment.

Or add your comments inside the function if you really want to localize
them, but do it something like this:

	/*
	 * my_integer_pi()
	 *
	 * This function calculates the value of PI, and returns
	 * 3. It does so by adding "1" in a loop three times.
	 */
	int my_integer_pi(void)
	{
		int i, pi;

		/*
		 * This is the main loop.
		 */
		pi = 0;
		for (i = 0; i < 3; i++)
			pi++;

		/* Ok, return it */
		return pi;
	}

Notice? Not AFTER the statements. 

Why? Because you are likely to want to change the statements. You don't
want to keep moving the comments around to line them up. And trying to
have a multi-line comment with code is just HORRIBLE:

		pi = 0;			/* Initialize our counter  */
		for (i = 0; i < 3; i++)	/* to zero before the loop */
			pi++;		/* Increment it.	   */

because the above turns into absolute mush if you change your code a bit
(maybe you decide to move the initialization up a bit, because you make
your function start off with a better approximation, and you want to use
another algorithm to calculate PI to more than zero decimal points. Now
you need to move the two-line comment around, and break it up etc etc.

In contrast, when you have comments on lines of their own, you just move
the whole comment block when you re-organize the code.

		Linus

-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
Please read the FAQ at http://www.tux.org/lkml/

       reply index

Thread overview: 60+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
     [not found] <Pine.LNX.4.10.10101192217390.9361-100000@penguin.transmeta .com>
     [not found] ` <3A68E309.2540A5E1@purplecoder.com>
2001-01-20  6:29   ` Linus Torvalds [this message]
2001-01-20 15:32   ` Anton Altaparmakov
2001-01-20 16:19     ` [OT?] " profmakx.fmp
2001-01-21  5:10       ` Ragnar Hojland Espinosa
2001-01-21  5:50         ` Admin Mailing Lists
2001-01-21  5:58           ` Mike A. Harris
2001-01-21  7:07             ` Josh Myer
2001-01-21  7:20           ` Alan Olsen
2001-01-21 22:40           ` Mo McKinlay
2001-01-22  0:23             ` Admin Mailing Lists
2001-01-21  8:24     ` george anzinger
2007-06-14 18:48 coding style Cyrill Gorcunov
2007-06-15  4:51 ` Willy Tarreau
2007-06-15  5:09   ` Kok, Auke
2007-06-15  6:38     ` dave young
2007-06-15  6:47       ` debian developer
2007-06-15  6:54         ` dave young
2007-06-15  9:16       ` Jan Engelhardt
2007-06-15 17:32         ` Cyrill Gorcunov
2007-06-15 17:54           ` Chris Friesen
2007-06-15 18:03             ` Randy Dunlap
2007-06-15 19:10               ` Jan Engelhardt
2007-06-15 19:18                 ` Cyrill Gorcunov
2007-06-15 19:21                   ` Kok, Auke
2007-06-15 19:29                     ` Cyrill Gorcunov
2007-06-15 19:31                     ` Jan Engelhardt
2007-06-15 19:41                       ` Cyrill Gorcunov
2007-06-15 20:21                         ` Linus Torvalds
2007-06-15 20:35                           ` Jan Engelhardt
2007-06-16 12:30                             ` Stefan Richter
2007-06-15 20:21                         ` Jan Engelhardt
2007-06-15 20:39                           ` Linus Torvalds
2007-06-16  6:38                             ` Jan Engelhardt
2007-06-16 12:40                               ` Stefan Richter
2007-06-16 15:49                               ` Linus Torvalds
2007-06-19 14:05                                 ` Mark Lord
2007-06-15 19:45                       ` Kok, Auke
2007-06-15 19:49                         ` Cyrill Gorcunov
2007-06-15 20:28                         ` Jan Engelhardt
2007-06-15 22:10                   ` Randy Dunlap
2007-06-15 18:05             ` Kok, Auke
2007-06-15 18:22               ` Cyrill Gorcunov
2007-06-16 13:07                 ` Stefan Richter
2007-06-16 14:31                   ` gorcunov
2007-06-16 17:43                     ` Stefan Richter
2007-06-16 18:22                       ` Cyrill Gorcunov
2007-06-16 14:22         ` Clifford Wolf
2007-06-15  8:56     ` Krzysztof Halasa
  -- strict thread matches above, loose matches on Subject: below --
2001-01-23 15:07 Coding Style Jonathan Earle
2001-01-24  3:23 ` john slee
2001-01-19 17:59 Mark I Manning IV
2001-01-20  0:09 ` David Ford
2001-01-20  1:26   ` John Cavan
2001-01-20  0:46 ` Albert D. Cahalan
2001-01-20  5:34   ` Linus Torvalds
2001-01-21  2:00 ` Matthias Andree
2001-01-22  8:24   ` Ralf Baechle
2001-01-22 22:28     ` Mark I Manning IV
2001-01-23  3:56       ` adrian
2001-01-23 20:05 ` Boris Dragovic

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=Pine.LNX.4.10.10101192217390.9361-100000@penguin.transmeta.com \
    --to=torvalds@transmeta.com \
    --cc=linux-kernel@vger.kernel.org \
    --cc=mark4@purplecoder.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

LKML Archive on lore.kernel.org

Archives are clonable:
	git clone --mirror https://lore.kernel.org/lkml/0 lkml/git/0.git
	git clone --mirror https://lore.kernel.org/lkml/1 lkml/git/1.git
	git clone --mirror https://lore.kernel.org/lkml/2 lkml/git/2.git
	git clone --mirror https://lore.kernel.org/lkml/3 lkml/git/3.git
	git clone --mirror https://lore.kernel.org/lkml/4 lkml/git/4.git
	git clone --mirror https://lore.kernel.org/lkml/5 lkml/git/5.git
	git clone --mirror https://lore.kernel.org/lkml/6 lkml/git/6.git
	git clone --mirror https://lore.kernel.org/lkml/7 lkml/git/7.git
	git clone --mirror https://lore.kernel.org/lkml/8 lkml/git/8.git
	git clone --mirror https://lore.kernel.org/lkml/9 lkml/git/9.git
	git clone --mirror https://lore.kernel.org/lkml/10 lkml/git/10.git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V2 lkml lkml/ https://lore.kernel.org/lkml \
		linux-kernel@vger.kernel.org
	public-inbox-index lkml

Example config snippet for mirrors

Newsgroup available over NNTP:
	nntp://nntp.lore.kernel.org/org.kernel.vger.linux-kernel


AGPL code for this site: git clone https://public-inbox.org/public-inbox.git