Re: Coding Style

Re: Coding Style

[Linus Torvalds]

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/

Re: Coding Style

[Anton Altaparmakov]

At 06:29 20/01/2001, Linus Torvalds wrote:
>On Fri, 19 Jan 2001, Mark I Manning IV wrote:
[snip]
> > > 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.

Would you not also add "unless you are defining structure definitions and 
want to explain what each of the struct members means"?

[snip]
>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:

And structs are not likely to change so this argument would not longer apply?

Just curious.

Regards,

         Anton


-- 
    "Programmers never die. They do a GOSUB without RETURN." - Unknown source
-- 
Anton Altaparmakov <aia21 at cam.ac.uk> (replace at with @)
Linux NTFS Maintainer
ICQ: 8561279 / WWW: http://www-stu.christs.cam.ac.uk/~aia21/

-
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/

Re: [OT?] Coding Style

[profmakx.fmp]

Hi

I just wanted to say that Linus´ CodingStyle is the ONLY SANE style of
writing code in bigger projects. At university we are forced to use exactly the
braindamaged settings and styles that linux condemns. So, every good programmer
should know where to put comments. And it is unnecessary to put comments to
explain what code does. One should see this as stated in the CodingStyle doc.
Ok, there are points where a comment is good, but for example at university
we are to comment on every single line of code ...

So back to work now!

Markus

-- 
Sent through GMX FreeMail - http://www.gmx.net
-
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/

Re: [OT?] Coding Style

[Ragnar Hojland Espinosa]

On Sat, Jan 20, 2001 at 05:19:17PM +0100, profmakx.fmp@gmx.de wrote:
> I just wanted to say that Linus´ CodingStyle is the ONLY SANE style of
> writing code in bigger projects. At university we are forced to use exactly the

And the lord spake, saying, "First shalt thou write thy holy code. Indenting
shalt thou count to three, no more, no less.  Three shalt be the spaces thou 
shalt count, and the number of the counting shalt be three.  Four shalt thou
not count, nor count thou two, excepting that thou then proceedeth to three.
Eight is right out.  Once the number three, being the third number be
reached, shalt thou move towards indenting thy next line ..

.. ;)
-- 
____/|  Ragnar Højland     Freedom - Linux - OpenGL      Fingerprint  94C4B
\ o.O|                                                   2F0D27DE025BE2302C
 =(_)=  "Thou shalt not follow the NULL pointer for      104B78C56 B72F0822
   U     chaos and madness await thee at its end."
-
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/

Re: [OT?] Coding Style

[Admin Mailing Lists]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: TEXT/PLAIN; charset=X-UNKNOWN, Size: 1447 bytes --]


On Sun, 21 Jan 2001, Ragnar Hojland Espinosa wrote:

> On Sat, Jan 20, 2001 at 05:19:17PM +0100, profmakx.fmp@gmx.de wrote:
> > I just wanted to say that Linus´ CodingStyle is the ONLY SANE style of
> > writing code in bigger projects. At university we are forced to use exactly the
> 
> And the lord spake, saying, "First shalt thou write thy holy code. Indenting
> shalt thou count to three, no more, no less.  Three shalt be the spaces thou 
> shalt count, and the number of the counting shalt be three.  Four shalt thou
> not count, nor count thou two, excepting that thou then proceedeth to three.
> Eight is right out.  Once the number three, being the third number be
> reached, shalt thou move towards indenting thy next line ..
> 

now I know why I never read the bible.

people jsut dont know how old cryptography really is ;-)

-Tony
.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-.
Anthony J. Biacco                       Network Administrator/Engineer
thelittleprince@asteroid-b612.org       Intergrafix Internet Services

    "Dream as if you'll live forever, live as if you'll die today"
http://www.asteroid-b612.org                http://www.intergrafix.net
.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-.

-
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/

Re: [OT?] Coding Style

[Mike A. Harris]

On Sun, 21 Jan 2001, Admin Mailing Lists wrote:

>> And the lord spake, saying, "First shalt thou write thy holy code. Indenting
>> shalt thou count to three, no more, no less.  Three shalt be the spaces thou
>> shalt count, and the number of the counting shalt be three.  Four shalt thou
>> not count, nor count thou two, excepting that thou then proceedeth to three.
>> Eight is right out.  Once the number three, being the third number be
>> reached, shalt thou move towards indenting thy next line ..
>>
>
>now I know why I never read the bible.
>
>people jsut dont know how old cryptography really is ;-)

If I'm not mistaken, the above is a parody on Monty Python's Holy
Grail.  The Holy Hand Grenade of Antinoch if I'm correct.  It's
been a while..


----------------------------------------------------------------------
    Mike A. Harris  -  Linux advocate  -  Free Software advocate
          This message is copyright 2001, all rights reserved.
  Views expressed are my own, not necessarily shared by my employer.
----------------------------------------------------------------------
The day Microsoft makes something that doesn't suck,
is probably the day Microsoft starts making vacuum cleaners.
  -- Ernst Jan Plugge

-
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/

Re: [OT?] Coding Style

[Josh Myer]

We would never parody Monty Python! This is an excerpt from Judas, one of
the gospels that was in dispute.

I'm sorry, I must go, as there's a man in a military uniform here, shouting
at me to stop being silly...

-josh

On Sat, 20 Jan 2001 23:58:07 Mike A. Harris wrote:
> On Sun, 21 Jan 2001, Admin Mailing Lists wrote:
> 
> >> And the lord spake, saying, "First shalt thou write thy holy code.
.
> If I'm not mistaken, the above is a parody on Monty Python's Holy
> Grail.  The Holy Hand Grenade of Antinoch if I'm correct.  It's
> been a while..
> 
. 
(i modified Mike's copyrighted document. do i need to get a license from
all of the people he quoted as well as his? ;^)



-
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/

Re: [OT?] Coding Style

[Alan Olsen]

On Sun, 21 Jan 2001, Admin Mailing Lists wrote:

> > And the lord spake, saying, "First shalt thou write thy holy code. Indenting
> > shalt thou count to three, no more, no less.  Three shalt be the spaces thou 
> > shalt count, and the number of the counting shalt be three.  Four shalt thou
> > not count, nor count thou two, excepting that thou then proceedeth to three.
> > Eight is right out.  Once the number three, being the third number be
> > reached, shalt thou move towards indenting thy next line ..
> > 
> 
> now I know why I never read the bible.

I thought that was the indention rules for Python. ]:>

alan@ctrl-alt-del.com | Note to AOL users: for a quick shortcut to reply
Alan Olsen            | to my mail, just hit the ctrl, alt and del keys.
    "In the future, everything will have its 15 minutes of blame."

-
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/

Re: Coding Style

[george anzinger]

Anton Altaparmakov wrote:

> At 06:29 20/01/2001, Linus Torvalds wrote:
> 
>> On Fri, 19 Jan 2001, Mark I Manning IV wrote:
> 
> [snip]
> 
>>  > > 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.
> 
> 
> Would you not also add "unless you are defining structure definitions 
> and want to explain what each of the struct members means"?
> 
> [snip]
> 
>> 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:
> 
> 
> And structs are not likely to change so this argument would not longer 
> apply?
> 
> Just curious.

I am curious about another style issue.  In particular _inline_ in ".h" 
files.  The "style" for this as practiced today is about to run into a 
brick wall.  Try, for example, referring to "current->need_resched" 
within the spin_lock() macro.  I don't think you can get this to work 
with the current kernel, and if you can, a) let me know how, and b) it 
is much too hard.  Imho it is time to rethink how (or where) we put 
_inline_ code.

I think the problem could be fixed by a convention in the compiler that 
says something like "_inline_" code will be compiled when a reference to 
it is encountered, but this is outside the standard (i.e. the standard 
allows it to be as it is and does not disallow my proposed convention, 
as I understand the standard).

George




-
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/

Re: [OT?] Coding Style

[Mo McKinlay]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Today, Admin Mailing Lists (mlist@intergrafix.net) wrote:

  > > And the lord spake, saying, "First shalt thou write thy holy code. Indenting
  > > shalt thou count to three, no more, no less.  Three shalt be the spaces thou
  > > shalt count, and the number of the counting shalt be three.  Four shalt thou
  > > not count, nor count thou two, excepting that thou then proceedeth to three.
  > > Eight is right out.  Once the number three, being the third number be
  > > reached, shalt thou move towards indenting thy next line ..

  > now I know why I never read the bible.

..or Monty Python...

- -- 
Mo McKinlay
mmckinlay@gnu.org
- -------------------------------------------------------------------------
GnuPG/PGP Key: pub  1024D/76A275F9 2000-07-22









-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.4 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iEYEARECAAYFAjprZWUACgkQRcGgB3aidfnz0gCgqOGt7dg3cZH/uDz0Vpe/P9Fe
ALsAn2y2L/D9e1QRWTb6jDSM+kvsrShr
=3D28
-----END PGP SIGNATURE-----

-
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/

Re: [OT?] Coding Style

[Admin Mailing Lists]

well, i watched monty python and the holy grail once (had to find out what
everyone was all excited about) couldn't get into it, watched maybe 1/2 of
it.

-Tony 
.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-.
Anthony J. Biacco                       Network Administrator/Engineer
thelittleprince@asteroid-b612.org       Intergrafix Internet Services

    "Dream as if you'll live forever, live as if you'll die today"
http://www.asteroid-b612.org                http://www.intergrafix.net
.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-.

On Sun, 21 Jan 2001, Mo McKinlay wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Today, Admin Mailing Lists (mlist@intergrafix.net) wrote:
> 
>   > > And the lord spake, saying, "First shalt thou write thy holy code. Indenting
>   > > shalt thou count to three, no more, no less.  Three shalt be the spaces thou
>   > > shalt count, and the number of the counting shalt be three.  Four shalt thou
>   > > not count, nor count thou two, excepting that thou then proceedeth to three.
>   > > Eight is right out.  Once the number three, being the third number be
>   > > reached, shalt thou move towards indenting thy next line ..
> 
>   > now I know why I never read the bible.
> 
> ..or Monty Python...
> 
> - -- 
> Mo McKinlay
> mmckinlay@gnu.org
> - -------------------------------------------------------------------------
> GnuPG/PGP Key: pub  1024D/76A275F9 2000-07-22
> 
> 
> 
> 
> 
> 
> 
> 
> 
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.0.4 (GNU/Linux)
> Comment: For info see http://www.gnupg.org
> 
> iEYEARECAAYFAjprZWUACgkQRcGgB3aidfnz0gCgqOGt7dg3cZH/uDz0Vpe/P9Fe
> ALsAn2y2L/D9e1QRWTb6jDSM+kvsrShr
> =3D28
> -----END PGP SIGNATURE-----
> 
> -
> 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/
> 

-
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/

Re: [OT?] Coding Style

[James Stevenson]

>
>> Then there is reasability.
>>
>>   void ThisIsMyDumbassFunctionName
>>

so how many times have you typed something like
ThisIsMyDumbAssFunctionName instead of
ThisIsMyDumbassFunctionName


>> if MUCH more difficult to read than
>>
>>   void this_is_my_clear_and_easy_function_name
>
>I can certainly read the first easier than the second.
>
>MfG Kai


-- 
---------------------------------------------
Check Out: http://stev.org
E-Mail: mistral@stev.org
 12:10am  up 10 days,  7:31,  4 users,  load average: 0.16, 0.04, 0.10
-
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/

Re: [OT?] Coding Style

[Harald Arnesen]

kaih@khms.westfalen.de (Kai Henningsen) writes:

> >   void ThisIsMyDumbassFunctionName
> >
> > if MUCH more difficult to read than
> >
> >   void this_is_my_clear_and_easy_function_name
> 
> I can certainly read the first easier than the second.

So I assume you don't approve of the new German spelling standard,
where nouns with capital letters are optional (don't know if it became
reality, I remember reading that Günther Grass was against it).

For a Norwegian, the second variant is much more readable.
-- 
Harald Arnesen, Apalløkkveien 23 A, N-0956 Oslo, Norway
-
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/

Re: [OT?] Coding Style

[Kai Henningsen]

kodis@mail630.gsfc.nasa.gov (John Kodis)  wrote on 23.01.01 in <20010123124216.A30552@tux.gsfc.nasa.gov>:

> On Tue, Jan 23, 2001 at 10:41:49AM -0500, Jonathan Earle wrote:
>
> > One thing I wonder though... why do people prefer 'some_function_name()'
> > over 'SomeFunctionName()'?
>
> i_would_assume_that_it_is_because_the_underscore_serves_the_same_word-
> seperation_role_that_a_space_does_in_normal_prose.  RunningWordsAll
> Together(OrShouldISay"ToGetHer"ForMaximumStudlyness)JustDoesNotParseAs
> Readily, and that, rather that ease of typing is what counts.

Nice example: the underscore part was in fact *much* harder to read for  
me. The second part read nearly exactly like normally spaced text.

Maybe there is something to the thesis that it depends on what people are  
accustomed to: English uses far less capital letters than German, and I  
certainly prefer the German capitalization style.

MfG Kai
-
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/

Re: [OT?] Coding Style

[Kai Henningsen]

steveu@coppice.org (Steve Underwood)  wrote on 24.01.01 in <3A6E2C6E.632CDABF@coppice.org>:

> Unfortunately the C standards people don't seem to realise there are
> languages other than English. C99 had perfect timing to introduce UTF8
> Unicode as acceptable in C source. Alas they missed the boat. I have
> been embedding Chinese in C source for years (mostly Big-5 -  UTF8 is
> more likely to be troublesome with existing compilers), and have yet to
> hit a significant problem. It isn't standards compliant, though.

Have you *READ* the C99 standard? According to my copy of ISO/IEC  
9899:1999, chinese characters in identifiers are quite legal.

And the source is not defined to be UTF8 because C has never defined the  
source to be any specific character set; if your character set does not  
include the right characters, use \uXXXX or \Uxxxxxxxx.

MfG Kai
-
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/

Re: [OT?] Coding Style

[Kai Henningsen]

mharrold@cas.org (Mike Harrold)  wrote on 23.01.01 in <200101231600.LAA24562@mah21awu.cas.org>:

> > I prefer descriptive variable and function names - like comments, they
> > help to make code so much easier to read.
> >
> > One thing I wonder though... why do people prefer 'some_function_name()'
> > over 'SomeFunctionName()'?  I personally don't like the underscore
> > character - it's an odd character to type when you're trying to get the
> > name typed in, and the shifted character, I find, is easier to input.
> >
>
> For exactly the reverse of that reason. Typing capital letters is a heck
> of a lot more difficult that addint an underscore.

(shift)+(-_) is a lot more more difficult than (shift)+(A)?

Or do you have a keyboard layout where _ is not a shifted key?

> Then there is reasability.
>
>   void ThisIsMyDumbassFunctionName
>
> if MUCH more difficult to read than
>
>   void this_is_my_clear_and_easy_function_name

I can certainly read the first easier than the second.

MfG Kai
-
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/

Re: [OT?] Coding Style

[Andre Hedrick]

Apologies first...

Would someone send me a way to filter mail?

I REALLY DO NOT GIVE A RATS ARSE ABOUT THIS OT!!

Like it or Leave it but whinning about it SUX!

Regard,
Cheif Whinner!

-
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/

Re: [OT?] Coding Style

[Brent Rowland]

> Too bad we can't just do a "Prince" and invent unpronouncable symbols to 
> use as function names... or perhaps just use something from the chinese 
> fonts ;o)...

Sorry.  You'll need to use Java if you want to use Unicode source.

Brent


-
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/

Re: [OT?] Coding Style

[Steve Underwood]

Unfortunately the C standards people don't seem to realise there are
languages other than English. C99 had perfect timing to introduce UTF8
Unicode as acceptable in C source. Alas they missed the boat. I have
been embedding Chinese in C source for years (mostly Big-5 -  UTF8 is
more likely to be troublesome with existing compilers), and have yet to
hit a significant problem. It isn't standards compliant, though.

Regards,
Steve


Joe deBlaquiere wrote:
> 
> Too bad we can't just do a "Prince" and invent unpronouncable symbols to
> use as function names... or perhaps just use something from the chinese
> fonts ;o)...
> 
> Mike Harrold wrote:
> 
> >> This message is in MIME format. Since your mail reader does not understand
> >> this format, some or all of this message may not be legible.
> >>
> >> ------_=_NextPart_001_01C08552.FFC336D0
> >> Content-Type: text/plain;
> >>      charset="ISO-8859-1"
> >>
> >> I prefer descriptive variable and function names - like comments, they help
> >> to make code so much easier to read.
> >>
> >> One thing I wonder though... why do people prefer 'some_function_name()'
> >> over 'SomeFunctionName()'?  I personally don't like the underscore character
> >> - it's an odd character to type when you're trying to get the name typed in,
> >> and the shifted character, I find, is easier to input.
> >>
> >
> >
> > For exactly the reverse of that reason. Typing capital letters is a heck
> > of a lot more difficult that addint an underscore.
> >
> > Then there is reasability.
> >
> >   void ThisIsMyDumbassFunctionName
> >
> > if MUCH more difficult to read than
> >
> >   void this_is_my_clear_and_easy_function_name
-
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/

RE: [OT?] Coding Style

[Stephen Satchell]

At 10:47 AM 1/23/01 -0600, Jesse Pollard wrote:
>Code is written by the few.
>Code is read by the many, and having _ in there makes it MUCH easier to
>read. Visual comparison of "SomeFunctionName" and "some_function_name"
>is faster even for a coder where there may be a typo (try dropping a 
>character)
>or mis identifing two different symbols with similar names:
>
>         d_hash_mask
>         d_hash_shift
>
>This is relatively easy to read. conversely:
>
>         DHashMask
>         DHashShift
>
>Are more difficult to spot.

Depends on what you are used to.  I'm used to both, being both an old-world 
C programmer from the very beginning (where underscore was the preferred 
way) and also a Pascal programmer (where the mixed-case form was the 
preferred way).  Remember a language where dollar signs broke up words?

But then again, one reason I'm so fond of structures is that you can get 
away from the whole thing by being able to read

        d.hash.mask
        d.hash.shift

(It's really too bad that you can't have structured enum constants, isn't it?)

By the way, just so everyone hates me, I would tend to key the above two 
names as

      DHash_mask
      DHash_shift

so that, as another person has commented, you identify the class of a 
variable and the specifics as easily identifiable entities.  That assumes 
that your "class" names are sufficiently different that a mis-key will be 
caught by that master of book-keeping, the compiler.

-
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/

RE: [OT?] Coding Style

[Jonathan Earle]

That's just nasty!   Funny, but nasty. :)

Jon

> -----Original Message-----
> From: Stephen Satchell [mailto:satch@fluent-access.com]

> It took a while to prepare the source for this jerk.  Here is 
> what I did to 
> the source I gave the guy:
-
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/

Re: [OT?] Coding Style

[David Benfell]

[-- Attachment #1: Type: text/plain, Size: 3364 bytes --]

On Tue, Jan 23, 2001 at 05:17:15PM +0100, Nicolas Noble wrote:
> 
> >     a = b + c; /* add a to b, and store it as c */
> 
> I think *this* comment is very fun, since it make me asking myself if I
> really know the C language :)
> 
I trust we all got a chuckle out of this one.

I come from an era where obscure code was the rule and we were just
glad to have comments.  So it's a little bit of a wake-up call when I
see the current debate.

There are a couple of memorable points I've seen so far here:

1) Linus points out that if you change the code, it will usually break
the formatting of a trailing comment.

2) A complaint that comments often don't jive with the code.

I think we're missing something here, mainly point #2.  If you're
paying attention to the comments when you're modifying the code, point
#1 becomes a lot less critical because you should also be updating the
comments.

To state what (to me) seems like it must be obvious:

Sometimes solutions to problems are obviously correct.  Sometimes they
aren't so obviously correct (emphasis on obviously).  And, try as you
might, the increased complexity of modern code must surely have led to
new boobytraps.  Comments are appropriate whenever the right solution
is not obviously correct or whenever you're tiptoeing through a
minefield of issues.  They are appropriate whenever and wherever you
choose an efficient solution over one which is "human-readable."
Comments should be mandatory wherever you generate code which might be
misunderstood or when an obvious solution to one problem also happens
to fix something else which is a less obvious.

The argument which was made a while ago, which I think bears repeating
here, is that code serves two purposes:

1) the mechanical process of instructing the machine to do something.
2) to clearly communicate its purpose to any who may come later.

The first point is obvious.  The second leads to lots of arguments on
style.  (So programmers still don't want to type out long variable
names?)

What I would argue for here is the application of common sense.  Write
a piece of code.  Comment it as appropriate.  Then look at it as if
you were attempting to explain it to someone else, not necessarily as
gifted as yourself.  All of your explanation should be there, in
writing in well-formatted comments or in readable code.  Your code has
a purpose (to solve a problem); it often helps to clearly state what
that problem is, then how your code addresses it.

Very often, this explanation takes a lot more space than you can tack
on at the end of a line of code.  In that case, the comments should go
right where Linus says he wants them, in advance of the code you're
documenting, in near-essay form.

The point here is that the communication is the important thing.  In
your haste to just generate that quick fix, you waste time later when
you or someone else tries to unravel what the hell you did.  This is
not a new argument.  I remember hearing it in school 25 years ago (so
you know it must be even older than that).

-- 
David Benfell
benfell@greybeard95a.com
---
The grand leap of the whale up the Fall of Niagara is esteemed, by all
who have seen it, as one of the finest spectacles in nature.
                -- Benjamin Franklin.

				[from fortune]

		 

[-- Attachment #2: Type: application/pgp-signature, Size: 240 bytes --]

Re: [OT?] Coding Style

[Alan Olsen]

On Tue, 23 Jan 2001, Helge Hafting wrote:

> Stephen Satchell wrote:
> 
> [lots of good advice deleted]
> > One goal of language designers is to REMOVE the need for comments.  With a
> > good fourth-generation or fifth-generation language, the need for comments
> > diminishes to a detailed description of the data sets and any highly
> > unusual operations or transforms on the data.
> 
> This is but a dream.  You can't "design out" the need for comments by
> approaching natural language.  Try reading a law book and realize that
> natural language too may be twisted to the extent that it needs
> extensive comments.  The same goes for any computer language powerful
> enough to do useful work.

Actually using natural language and other such constructs may INCREASE the
need for comments.

For more examples, see Perl.

alan@ctrl-alt-del.com | Note to AOL users: for a quick shortcut to reply
Alan Olsen            | to my mail, just hit the ctrl, alt and del keys.
    "In the future, everything will have its 15 minutes of blame."

-
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/

Re: [OT?] Coding Style

[James Kelly]

I am not sure about Linux IDEs, but when I programmed Objective-C using the 
OpenStep IDE, you could not only do auto-completion on those, but on any 
word that had been previously used.  That was cool, and didn't cause wacky 
problems like you might think it would (auto-completing words like the, to, 
for, etc when trying to type something else).

JBuilder comes close, so I am guessing the Klyx will also.  I sent an email 
suggestion to Inprise, excuse me..Borland, on the subject last year.  They 
seemed to like it.

jk

At 01:05 PM 1/23/01 -0500, Christopher Friesen wrote:
>This is why the autocompletion of functions and struct members in VC++ is
>awfully nice...hit the first few unique letters and it will complete the 
>rest of
>the function for you, then hit tab and keep going.  Is there anything with 
>that
>functionality under Linux?
>
>Chris

-
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/

Re: [OT?] Coding Style

[Georg Nikodym]

>>>>> "CF" == Christopher Friesen <cfriesen@nortelnetworks.com> writes:

 CF> This is why the autocompletion of functions and struct members in
 CF> VC++ is awfully nice...hit the first few unique letters and it
 CF> will complete the rest of the function for you, then hit tab and
 CF> keep going.  Is there anything with that functionality under
 CF> Linux?

Yup.  Emacs users can use the mis-named dynamic abbreviation function
(daddrev-expand which I have mapped to M-/).
-
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/

Re: [OT?] Coding Style

[Mathieu Chouquet-Stringer]

cfriesen@nortelnetworks.com ("Christopher Friesen") writes:

> Georg Nikodym wrote:
> 
> > I think that the distinction is moot and this argument a waste of
> > time.  If you are anything more than a code tourist, you should have
> > no trouble dealing with mnemonic names.  So the above can become:
> > 
> > /*
> >  * timcaefn == this is my clear and easy function name
> >  */
> > void timcaefn (void);
> > 
> > If you're at all concerned about RSI, your fingers will thank you.
> 
> This is why the autocompletion of functions and struct members in VC++ is
> awfully nice...hit the first few unique letters and it will complete the rest of
> the function for you, then hit tab and keep going.  Is there anything with that
> functionality under Linux?

Esc-/ under emacs...
-- 
Mathieu CHOUQUET-STRINGER              E-Mail : mchouque@e-steel.com
     Learning French is trivial: the word for horse is cheval, and
               everything else follows in the same way.
                        -- Alan J. Perlis
-
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/

Re: [OT?] Coding Style

[Stephen Satchell]

At 08:28 PM 1/23/01 +0800, Steve Underwood wrote:
>During a period of making a liveing out of
>sorting out severly screwed up projects I made a little comment
>stripper. I found comments so unreliable, and so seldom useful, I was
>better off reading the code without the confusion they might cause. I
>do, however, try to document the non-obvious through comments in what I
>write.

Ditto.  Mine had the option of leaving the block comments in place (line 
count was a parameter) because the block comments proved to be more useful 
than the in-line comments.

>Some people still seem to be living in the age of K&R C, with 6 or 7
>character variable names that demand some explanation. Maybe some day
>they will awake to the expressive power of long (and well chosen) names.

Actually, they are still living as though the KSR-33 and ASR-33 teletypes 
were the only input device.  :)

True story:  I was retained to solve a particular problem for a company 
over a one-year time period.  I wrote some rather nifty code to solve the 
problem, and was happily doing data extraction and conversion for that time 
period.  Then there was a management turnover at the client and the new guy 
decided to implement a cost-cutting measure:  cut out as many outsiders as 
possible.  He decided that I should give him the code I had developed over 
the year (that wasn't part of the contract, of course) so that he could 
have in-house people do it.  Not just executable programs, of course.  "We 
bought the development of that code, so we deserve the source."  The 
bastard backed up the demand with his lawyer.  Not wanting to spend the 
money on the threatened lawsuit, I gave him exactly what he asked for:  the 
source to the latest working version of the programs I wrote to do the job.

It took a while to prepare the source for this jerk.  Here is what I did to 
the source I gave the guy:

1)  Used the output of CPP, which stripped out all include files and strips 
all comments.  This had the interesting side effect of making the source 
compiler-dependent.
2)  Stripped all newlines, and converted strings of spaces and tabs not in 
quotes to a single space.  This made the source one line long...a VERY LONG 
line.
3)  Converted each reasonable variable name to a string of seven random 
characters from the set [A-Aa-z0-9_], with the first character restricted 
to [A-Za-z].  A list of #define statements equated the random name to the 
proper library name or symbol.  (Because the names included a number of 
internal variables in the compiler library, this was a HUGE list.)  The 
resulting symbol table was so large that I had to use disk to keep all the 
names.  Inadvertently I had also randomized lexical elements such as "for", 
"while" and so forth, but #define statements took care of that problem.
4)  Determined that the output of the compiler with the mangled source was 
exactly the same as the output of the compiler with the original source.

As you can guess, I discovered a few bugs with the compiler I was 
using.  The compiler writer (who was just down the road) was highly amused 
with this and asked if they could "borrow" my mangler "for test 
purposes."  (Just who do they think they were kiddin'?)

Satch

-
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/

Re: [OT?] Coding Style

[Christopher Friesen]

Georg Nikodym wrote:

> I think that the distinction is moot and this argument a waste of
> time.  If you are anything more than a code tourist, you should have
> no trouble dealing with mnemonic names.  So the above can become:
> 
> /*
>  * timcaefn == this is my clear and easy function name
>  */
> void timcaefn (void);
> 
> If you're at all concerned about RSI, your fingers will thank you.

This is why the autocompletion of functions and struct members in VC++ is
awfully nice...hit the first few unique letters and it will complete the rest of
the function for you, then hit tab and keep going.  Is there anything with that
functionality under Linux?

Chris


-- 
Chris Friesen                    | MailStop: 043/33/F10  
Nortel Networks                  | work: (613) 765-0557
3500 Carling Avenue              | fax:  (613) 765-2986
Nepean, ON K2H 8E9 Canada        | email: cfriesen@nortelnetworks.com
-
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/

Re: [OT?] Coding Style

[John Kodis]

On Tue, Jan 23, 2001 at 10:41:49AM -0500, Jonathan Earle wrote:

> One thing I wonder though... why do people prefer 'some_function_name()'
> over 'SomeFunctionName()'?  

i_would_assume_that_it_is_because_the_underscore_serves_the_same_word-
seperation_role_that_a_space_does_in_normal_prose.  RunningWordsAll
Together(OrShouldISay"ToGetHer"ForMaximumStudlyness)JustDoesNotParseAs
Readily, and that, rather that ease of typing is what counts.

-- 
John Kodis <kodis@acm.org>
Phone: 301-286-7376
-
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/

RE: [OT?] Coding Style

[Jesse Pollard]

"Jonathan Earle" <jearle@nortelnetworks.com>:
> I prefer descriptive variable and function names - like comments, they help
> to make code so much easier to read.
> 
> One thing I wonder though... why do people prefer 'some_function_name()'
> over 'SomeFunctionName()'?  I personally don't like the underscore character
> - it's an odd character to type when you're trying to get the name typed in,
> and the shifted character, I find, is easier to input.

Code is written by the few.
Code is read by the many, and having _ in there makes it MUCH easier to
read. Visual comparison of "SomeFunctionName" and "some_function_name"
is faster even for a coder where there may be a typo (try dropping a character)
or mis identifing two different symbols with similar names:

	d_hash_mask
	d_hash_shift

This is relatively easy to read. conversely:

	DHashMask
	DHashShift

Are more difficult to spot. 

In this case "The good of the many outweigh the good of the few".

-------------------------------------------------------------------------
Jesse I Pollard, II
Email: pollard@navo.hpc.mil

Any opinions expressed are solely my own.
-
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/

Re: [OT?] Coding Style

[Joe deBlaquiere]

Too bad we can't just do a "Prince" and invent unpronouncable symbols to 
use as function names... or perhaps just use something from the chinese 
fonts ;o)...

Mike Harrold wrote:

>> This message is in MIME format. Since your mail reader does not understand
>> this format, some or all of this message may not be legible.
>> 
>> ------_=_NextPart_001_01C08552.FFC336D0
>> Content-Type: text/plain;
>> 	charset="ISO-8859-1"
>> 
>> I prefer descriptive variable and function names - like comments, they help
>> to make code so much easier to read.
>> 
>> One thing I wonder though... why do people prefer 'some_function_name()'
>> over 'SomeFunctionName()'?  I personally don't like the underscore character
>> - it's an odd character to type when you're trying to get the name typed in,
>> and the shifted character, I find, is easier to input.
>> 
> 
> 
> For exactly the reverse of that reason. Typing capital letters is a heck
> of a lot more difficult that addint an underscore.
> 
> Then there is reasability.
> 
>   void ThisIsMyDumbassFunctionName
> 
> if MUCH more difficult to read than
> 
>   void this_is_my_clear_and_easy_function_name
> 
> Regards,
> 
> /Mike
> 
> 
>> Cheers!
>> Jon
>> 
>> 
>>> -----Original Message-----
>>> From: Steve Underwood [mailto:steveu@coppice.org]
>> 
>> Some people still seem to be living in the age of K&R C, with 6 or 7
>> character variable names that demand some explanation. Maybe some day
>> they will awake to the expressive power of long (and well chosen) names.
>> 
>> ------_=_NextPart_001_01C08552.FFC336D0
>> Content-Type: text/html;
>> 	charset="ISO-8859-1"
>> Content-Transfer-Encoding: quoted-printable
>> 
>> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
>> <HTML>
>> <HEAD>
>> <META HTTP-EQUIV=3D"Content-Type" CONTENT=3D"text/html; =
>> charset=3DISO-8859-1">
>> <META NAME=3D"Generator" CONTENT=3D"MS Exchange Server version =
>> 5.5.2652.35">
>> <TITLE>RE: [OT?] Coding Style</TITLE>
>> </HEAD>
>> <BODY>
>> 
>> <P><FONT SIZE=3D2>I prefer descriptive variable and function names - =
>> like comments, they help to make code so much easier to read.</FONT>
>> </P>
>> 
>> <P><FONT SIZE=3D2>One thing I wonder though... why do people prefer =
>> 'some_function_name()' over 'SomeFunctionName()'?&nbsp; I personally =
>> don't like the underscore character - it's an odd character to type =
>> when you're trying to get the name typed in, and the shifted character, =
>> I find, is easier to input.</FONT></P>
>> 
>> <P><FONT SIZE=3D2>Cheers!</FONT>
>> <BR><FONT SIZE=3D2>Jon</FONT>
>> </P>
>> 
>> <P><FONT SIZE=3D2>&gt; -----Original Message-----</FONT>
>> <BR><FONT SIZE=3D2>&gt; From: Steve Underwood [<A =
>> HREF=3D"mailto:steveu@coppice.org">mailto:steveu@coppice.org</A>]</FONT>=
>> 
>> </P>
>> 
>> <P><FONT SIZE=3D2>Some people still seem to be living in the age of =
>> K&amp;R C, with 6 or 7</FONT>
>> <BR><FONT SIZE=3D2>character variable names that demand some =
>> explanation. Maybe some day</FONT>
>> <BR><FONT SIZE=3D2>they will awake to the expressive power of long (and =
>> well chosen) names.</FONT>
>> </P>
>> 
>> </BODY>
>> </HTML>
>> ------_=_NextPart_001_01C08552.FFC336D0--
>> -
>> 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/
>> 
> 
> 
> -
> 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/


-- 
Joe deBlaquiere
Red Hat, Inc.
307 Wynn Drive
Huntsville AL, 35805
voice : (256)-704-9200
fax   : (256)-837-3839

-
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/

Re: [OT?] Coding Style

[Nicolas Noble]

>     a = b + c; /* add a to b, and store it as c */

I think *this* comment is very fun, since it make me asking myself if I
really know the C language :)

-
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/

Re: [OT?] Coding Style

[Georg Nikodym]

>>>>> "MH" == Mike Harrold <mharrold@cas.org> writes:

 MH> For exactly the reverse of that reason. Typing capital letters is
 MH> a heck of a lot more difficult that addint an underscore.

 MH> Then there is reasability.

 MH> void ThisIsMyDumbassFunctionName

 MH> if MUCH more difficult to read than

 MH> void this_is_my_clear_and_easy_function_name

I think that the distinction is moot and this argument a waste of
time.  If you are anything more than a code tourist, you should have
no trouble dealing with mnemonic names.  So the above can become:

/*
 * timcaefn == this is my clear and easy function name
 */
void timcaefn (void);

If you're at all concerned about RSI, your fingers will thank you.

:-) :-) :-)
-
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/

Re: [OT?] Coding Style

[Mike Harrold]

> 
> This message is in MIME format. Since your mail reader does not understand
> this format, some or all of this message may not be legible.
> 
> ------_=_NextPart_001_01C08552.FFC336D0
> Content-Type: text/plain;
> 	charset="ISO-8859-1"
> 
> I prefer descriptive variable and function names - like comments, they help
> to make code so much easier to read.
> 
> One thing I wonder though... why do people prefer 'some_function_name()'
> over 'SomeFunctionName()'?  I personally don't like the underscore character
> - it's an odd character to type when you're trying to get the name typed in,
> and the shifted character, I find, is easier to input.
> 

For exactly the reverse of that reason. Typing capital letters is a heck
of a lot more difficult that addint an underscore.

Then there is reasability.

  void ThisIsMyDumbassFunctionName

if MUCH more difficult to read than

  void this_is_my_clear_and_easy_function_name

Regards,

/Mike

> Cheers!
> Jon
> 
> > -----Original Message-----
> > From: Steve Underwood [mailto:steveu@coppice.org]
> 
> Some people still seem to be living in the age of K&R C, with 6 or 7
> character variable names that demand some explanation. Maybe some day
> they will awake to the expressive power of long (and well chosen) names.
> 
> ------_=_NextPart_001_01C08552.FFC336D0
> Content-Type: text/html;
> 	charset="ISO-8859-1"
> Content-Transfer-Encoding: quoted-printable
> 
> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
> <HTML>
> <HEAD>
> <META HTTP-EQUIV=3D"Content-Type" CONTENT=3D"text/html; =
> charset=3DISO-8859-1">
> <META NAME=3D"Generator" CONTENT=3D"MS Exchange Server version =
> 5.5.2652.35">
> <TITLE>RE: [OT?] Coding Style</TITLE>
> </HEAD>
> <BODY>
> 
> <P><FONT SIZE=3D2>I prefer descriptive variable and function names - =
> like comments, they help to make code so much easier to read.</FONT>
> </P>
> 
> <P><FONT SIZE=3D2>One thing I wonder though... why do people prefer =
> 'some_function_name()' over 'SomeFunctionName()'?&nbsp; I personally =
> don't like the underscore character - it's an odd character to type =
> when you're trying to get the name typed in, and the shifted character, =
> I find, is easier to input.</FONT></P>
> 
> <P><FONT SIZE=3D2>Cheers!</FONT>
> <BR><FONT SIZE=3D2>Jon</FONT>
> </P>
> 
> <P><FONT SIZE=3D2>&gt; -----Original Message-----</FONT>
> <BR><FONT SIZE=3D2>&gt; From: Steve Underwood [<A =
> HREF=3D"mailto:steveu@coppice.org">mailto:steveu@coppice.org</A>]</FONT>=
> 
> </P>
> 
> <P><FONT SIZE=3D2>Some people still seem to be living in the age of =
> K&amp;R C, with 6 or 7</FONT>
> <BR><FONT SIZE=3D2>character variable names that demand some =
> explanation. Maybe some day</FONT>
> <BR><FONT SIZE=3D2>they will awake to the expressive power of long (and =
> well chosen) names.</FONT>
> </P>
> 
> </BODY>
> </HTML>
> ------_=_NextPart_001_01C08552.FFC336D0--
> -
> 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/
> 

-
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/

Re: [OT?] Coding Style

[Larry McVoy]

On Tue, Jan 23, 2001 at 10:41:49AM -0500, Jonathan Earle wrote:
> I prefer descriptive variable and function names - like comments, they help
> to make code so much easier to read.
> 
> One thing I wonder though... why do people prefer 'some_function_name()'
> over 'SomeFunctionName()'?  I personally don't like the underscore character
> - it's an odd character to type when you're trying to get the name typed in,
> and the shifted character, I find, is easier to input.

I have a tendency to use class_functionName() where "class" represents a
class of related functions.  They all tend to take a point to an instance
of that "class".  So then you can read the code and see the "classes" in
the names.

And, this way, I can piss off both the anti underscore and the anti mixed case
people at the same time :-)
-- 
---
Larry McVoy            	 lm at bitmover.com           http://www.bitmover.com/lm 
-
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/

RE: [OT?] Coding Style

[Jonathan Earle]

[-- Attachment #1: Type: text/plain, Size: 704 bytes --]

I prefer descriptive variable and function names - like comments, they help
to make code so much easier to read.

One thing I wonder though... why do people prefer 'some_function_name()'
over 'SomeFunctionName()'?  I personally don't like the underscore character
- it's an odd character to type when you're trying to get the name typed in,
and the shifted character, I find, is easier to input.

Cheers!
Jon

> -----Original Message-----
> From: Steve Underwood [mailto:steveu@coppice.org]

Some people still seem to be living in the age of K&R C, with 6 or 7
character variable names that demand some explanation. Maybe some day
they will awake to the expressive power of long (and well chosen) names.

[-- Attachment #2: Type: text/html, Size: 1302 bytes --]

Re: [OT?] Coding Style

[Andrew Morton]

Larry McVoy wrote:
> 
> Please don't listen to this.  The only place you really want comments is
> 
>     a) at the top of files, describing the point of the file;
>     b) at the top of functions, if the purpose of the function is not obvious;
>     c) in line, when the code is not obvious.

One other _very_ useful place: in header files.  This is a place where
a comment-per-line is appropriate.

For example, include/linux/fs.h.  Shame about `struct inode' though.

-
-
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/

Re: [OT?] Coding Style

[Steve Underwood]

Larry McVoy wrote:
> 
> On Mon, Jan 22, 2001 at 11:04:50AM -0500, Jonathan Earle wrote:
> > > -----Original Message-----
> > > From: profmakx.fmp [mailto:profmakx.fmp@gmx.de]
> > >
> > > So, every good programmer
> > > should know where to put comments. And it is unnecessary to
> > > put comments to
> > > explain what code does. One should see this as stated in the
> > > CodingStyle doc.
> > > Ok, there are points where a comment is good, but for example
> > > at university
> > > we are to comment on every single line of code ...
> >
> > WRONG!!!
> >
> > Not documenting your code is not a sign of good coding, but rather shows
> > arrogance, laziness and contempt for "those who would dare tamper with your
> > code after you've written it".  Document and comment your code thoroughly.
> > Do it as you go along.  I was also taught to comment nearly every line - as
> > part of the coding style used by a large, international company I worked for
> > several years ago.  It brings the logic of the programmer into focus and
> > makes code maintenance a whole lot easier.  It also helps one to remember
> > the logic of your own code when you revisit it a year or more hence.
> 
> Please don't listen to this.  The only place you really want comments is
> 
>     a) at the top of files, describing the point of the file;
>     b) at the top of functions, if the purpose of the function is not obvious;
>     c) in line, when the code is not obvious.
> 
> If you are writing code that requires a comment for every line, you are
> writing bad, obscure, unobvious code and no amount of commenting will fix
> it.
> 
> The real reason to sparing in your comments is that code and comments are
> not semantically bound to each other: the program doesn't stop working when
> the comment becomes incorrect.  It's incredibly frustrating to read a comment,
> believe you understand what is going on, only to find out that the comment
> and the code no longer match.
> --
> ---
> Larry McVoy              lm at bitmover.com           http://www.bitmover.com/lm

It seems the great majority of heavily commented programs I have seen
never commented anything useful. The ooooh so useful the little
snippets, like:

    /* Beware: The next two lines might seem weird, but they work around 
       a bug in some revisions of XYZZY. */

were seldom there, but:

    a = b + c; /* add a to b, and store it as c */

were there in bundles. During a period of making a liveing out of
sorting out severly screwed up projects I made a little comment
stripper. I found comments so unreliable, and so seldom useful, I was
better off reading the code without the confusion they might cause. I
do, however, try to document the non-obvious through comments in what I
write.

Some people still seem to be living in the age of K&R C, with 6 or 7
character variable names that demand some explanation. Maybe some day
they will awake to the expressive power of long (and well chosen) names.

Regards,
Steve
-
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/

Re: [OT?] Coding Style

[Helge Hafting]

Stephen Satchell wrote:

[lots of good advice deleted]
> One goal of language designers is to REMOVE the need for comments.  With a
> good fourth-generation or fifth-generation language, the need for comments
> diminishes to a detailed description of the data sets and any highly
> unusual operations or transforms on the data.

This is but a dream.  You can't "design out" the need for comments by
approaching natural language.  Try reading a law book and realize that
natural language too may be twisted to the extent that it needs
extensive comments.  The same goes for any computer language powerful
enough to do useful work.

Helge Hafting
-
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/

Re: [OT?] Coding Style

[Stephen Satchell]

At 11:56 PM 1/22/01 +0000, Anton Altaparmakov wrote:
>At 16:42 22/01/2001, Mark I Manning IV wrote:
>>Stephen Satchell wrote:
>> >                                              I got in the habit of using
>> >  structures to minimize the number of symbols I exposed. It also
>> > disambiguates local variables and parameters from file- and program-global
>> > variables.
>>
>>explain this one to me, i think it might be usefull...
>
>What might be meant is that instead of declaring variables my_module_var1, 
>my_module_var2, my_module_var3, etc. you declare a struct my_module { 
>var1; var2; var3; etc. }. Obviously in glorious technicolour formatting... (-;
>That's my interpretation anyway...

The first sentence is right on the money.  In addition to module variables, 
I define a global structure as:

      extern struct G {
          /* the real globals */
          } g;

and then in the main program I define the instance as "struct G g;"  This 
is more for apps than operating systems.

Further to the avoidance of pollution of the external global namespace, I 
define local functions as static.  Indeed, in one parser I had over 1400 
very small functions, none of them with external scope.  Instead, I defined 
a structure of function pointers and exposed one name to the rest of the 
world.  Sound stupid?  Well, that stupidity had its place:  the "opcode" in 
the pseudo-instruction stream was the offset into this structure of 
pointers to the pointer of interest, which made the main loop for the 
parser about five lines long, and not a switch statement to be seen.  Three 
of those lines were to handle unknown-opcodes...

I also am partial to arrays of function pointers when appropriate.  Ever 
think how easy it would be to implement a TCP stack that would handle the 
"lamp-test packet" as a single special case?  Granted, it results in a 
small amount of code bloat over the traditional in-line test method, but it 
does make you think about EVERY SINGLE ONE OF THE 64 COMBINATIONS of 
Urg/Ack/Psh/Rst/Syn/Fin (to use the labels from the 1985 version of RFC 
793) and what they really mean.  Especially the combination with all bits set.

Satch

-
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/

Re: [OT?] Coding Style

[Werner Almesberger]

Admin Mailing Lists wrote:
>    hand-holding of that magnitude. We don't write code for idiots.

But if you have to, you can at least enjoy it:
 - diversity makes life interesting: use switch() with local variables or
   without curly braces
 - de-referencing is like a hotel: the more stars, the better
 - observe proper punctuation: use the comma operator frequently
 - know thy C: few people know that 5[x] is valid, but they can usually
   guess what it does. They probably won't get x[5[y]], though.
 - know thy CPP: nest macros and exercise token-concatenation and
   stingification
 - if your code allows you to, put  #define while if  in some header file

- Werner (couldn't resist ;-)

-- 
  _________________________________________________________________________
 / Werner Almesberger, ICA, EPFL, CH           Werner.Almesberger@epfl.ch /
/_IN_N_032__Tel_+41_21_693_6621__Fax_+41_21_693_6610_____________________/
-
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/

Re: [OT?] Coding Style

[Larry McVoy]

On Mon, Jan 22, 2001 at 11:56:40PM +0000, Anton Altaparmakov wrote:
> At 16:42 22/01/2001, Mark I Manning IV wrote:
> >Stephen Satchell wrote:
> > >                                              I got in the habit of using
> > >  structures to minimize the number of symbols I exposed. It also
> > > disambiguates local variables and parameters from file- and program-global
> > > variables.
> >
> >explain this one to me, i think it might be usefull...
> 
> What might be meant is that instead of declaring variables my_module_var1, 
> my_module_var2, my_module_var3, etc. you declare a struct my_module { var1; 
> var2; var3; etc. }. Obviously in glorious technicolour formatting... (-;
> That's my interpretation anyway...

Mine too and I think it's a good idea.  I have code in BitKeeper where I
both did and did not do that for command line options and I much prefer
the structure version.

Another habit I used to use and have fallen out of, which is a bad idea, is
one where you use a prefix in stucture files so that you can see
the difference between

	p->st_mode
and
	p->f_mode

In other words, the prefix implies the structure name.  Early versions of the
C compiler had all structure fields (I mean _all_) in one name space so this
wasn't style, it was required.  I must say that it makes code more readable.
-- 
---
Larry McVoy            	 lm at bitmover.com           http://www.bitmover.com/lm 
-
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/

Re: [OT?] Coding Style

[Anton Altaparmakov]

At 16:42 22/01/2001, Mark I Manning IV wrote:
>Stephen Satchell wrote:
> >                                              I got in the habit of using
> >  structures to minimize the number of symbols I exposed. It also
> > disambiguates local variables and parameters from file- and program-global
> > variables.
>
>explain this one to me, i think it might be usefull...

What might be meant is that instead of declaring variables my_module_var1, 
my_module_var2, my_module_var3, etc. you declare a struct my_module { var1; 
var2; var3; etc. }. Obviously in glorious technicolour formatting... (-;
That's my interpretation anyway...

Anton


-- 
      "Education is what remains after one has forgotten everything he 
learned in school." - Albert Einstein
-- 
Anton Altaparmakov  Voice: +44-(0)1223-333541(lab) / +44-(0)7712-632205(mobile)
Christ's College    eMail: AntonA@bigfoot.com / aia21@cam.ac.uk
Cambridge CB2 3BU    ICQ: 8561279
United Kingdom       WWW: http://www-stu.christs.cam.ac.uk/~aia21/

-
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/

Re: [OT?] Coding Style

[Admin Mailing Lists]

> 
> Please don't listen to this.  The only place you really want comments is
> 
>     a) at the top of files, describing the point of the file;
>     b) at the top of functions, if the purpose of the function is not obvious;
>     c) in line, when the code is not obvious.
> 
> If you are writing code that requires a comment for every line, you are 
> writing bad, obscure, unobvious code and no amount of commenting will fix
> it.
> 

or 
1) your code-viewing audience is a bunch of 5 year olds
2) the person reading the code isn't a 'qualified' programmer. If they
   were, they'd most likely be able to understand the code without
   hand-holding of that magnitude. We don't write code for idiots.


-Tony
.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-.
Anthony J. Biacco                       Network Administrator/Engineer
thelittleprince@asteroid-b612.org       Intergrafix Internet Services

    "Dream as if you'll live forever, live as if you'll die today"
http://www.asteroid-b612.org                http://www.intergrafix.net
.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-._.-.


-
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/

RE: [OT?] Coding Style

[Stephen Satchell]

At 11:04 AM 1/22/01 -0500, you wrote:
>WRONG!!!
>
>Not documenting your code is not a sign of good coding, but rather shows
>arrogance, laziness and contempt for "those who would dare tamper with your
>code after you've written it".  Document and comment your code thoroughly.
>Do it as you go along.  I was also taught to comment nearly every line - as
>part of the coding style used by a large, international company I worked for
>several years ago.  It brings the logic of the programmer into focus and
>makes code maintenance a whole lot easier.  It also helps one to remember
>the logic of your own code when you revisit it a year or more hence.

Oh, those who refuse to study history are doomed to repeat it.

The COBOL language was created specifically to reduce the amount of 
commenting necessary in a program, because the English-like sentence 
structure could be read and understood by humans.  The FORTRAN language was 
created so that math types could "talk" in a language more familiar to 
them, letting the computer take care of the details about how to perform 
the specified task step-by-step.

One goal of language designers is to REMOVE the need for comments.  With a 
good fourth-generation or fifth-generation language, the need for comments 
diminishes to a detailed description of the data sets and any highly 
unusual operations or transforms on the data.

I've even gone so far as to "invent" my own languages, and the parsers to 
go with them, to reduce the need to comment by making the code easy for 
humans to read.  Not only are such systems easier to debug (with good 
language design) but are highly maintainable and usually not all that 
difficult to extend when necessary.

Remember, the line-by-line commenting requirement was mandatory in 
assembler programming, because the nature of assembler made you outline 
each step by tiring step.  When I worked for Rockwell, I was granted a 
partial wavier when I showed them my assembler-language commenting 
style:  pseudo-code at the top of each block of assembler code.  Blindly 
applying the rule to second-generation and later languages is just sloppy 
management, usually by people who don't understand coding.  (And yes, that 
includes some professors of computer science I have known.)

Comments do NOT make code maintenance easier.  Too many comments obscure 
what is really going on.  Linus' style actually increases the 
maintainability of the code, because if the code doesn't accurately show 
how it implements the goal specified in the block comment, the coder hasn't 
done his/her job.

Want to improve the maintainability of C code?  Consider the following:

1)  Keep functional parts small.  If the code won't fit in a hundred lines 
or so of code, then you haven't factored the problem well 
enough.  Functional parts != functions.  A program with thousands of 
well-encapsulated function parts strung together into a single function is 
easier to maintain than a "well-factored" program with its parts spread all 
over hell.  Diagnostic programmers have learned the hard way that factoring 
a program can make it difficult to ensure test coverage and even more 
difficult to determine if a part of the code is buggy or whether it found a 
hardware error that it was looking for.  This is why diagnostics tend to be 
rather long affairs with very few functions.

In my ANSI C code, you will see the following a lot:

#define DO /*syntactic sugar */

     DO {
        </* first functional part, with owned variables */
     }

     DO {
         </* next functional part, with its owned variables */
     }

and so forth.  The "DO" is visual syntactic sugar so that the sub-blocks 
have the same appearance as other blocks, such as if, while, and for.  An 
added bonus to this particular style element is that compilers can more 
easily detect problems if you forget to initialize the local variables, or 
define variables you end up not using.  This has saved me hours of tedious 
debugging of my own code.  From the maintenance standpoint, it means that 
the definition of local variables are near all usages of it, so you don't 
have to continuously page up or split-screen to see the definition (and 
initialization) of "foobar_at_will".

2)  Reduce visual complexity where possible.  Instead of using nested 
if-then-else statements, consider unrolling the nested 
statement.  Example:  {if (a && c)...; if (b && c)...; instead of {if (c) 
{if (a)...; if(b)...;}

This doesn't have to affect performance.  For example, you can have rules 
such as:

      ruleset = (a ? 1 : 0) | (b ? 2 : 0) | (c ? 4 : 0);
      if (ruleset == 5) {
      ...
      }
      if (ruleset == 6) {
      ...
      }

This particular method can eliminate multiple expensive tests, and can 
guarantee that a, b, and c are evaluated exactly once during a cycle.  This 
can improve performance.  Using AND, OR, and XOR can further increase the 
power of the technique without a performance hit.  (For understandability, 
I recommend strongly a considered use of symbolic bitmasks, however.)

3)  Make creative use of a run-on if statement to improve error detection 
and recording.  One of my tricks is to code the following statement in 
application programs:

      if(   (err = "input file can't be opened", in = fopen(filename, 
"rb"), in == NULL)
        ||  (err = "output file can't be opened", out = fopen(oname, "wb"), 
out = NULL)
        ...
          )
       {
       /* report the error that occurred, using the char * variable "err" 
to indicate the exact error. */
       }

This means that I don't have to explicitly remember to code error routines 
for each and every function call, but the error detection coverage is much, 
much improved.  I used this technique in an IEEE-488 driver to detect 
errors in every step of the way, and it took LESS time to do it this way 
than to unroll the if statement because of the inherent tracing that the 
technique implements.

4)  The functional part should be contained in a reasonable number of 
lines.  Large while and for loops should call functions instead of having 
bloated bodies.  Large case statements should call functions instead of 
running on and on and on.

5)  For those statements that take compound statements (if, else, while, 
for, do while) the statement should ALWAYS be a compound 
statement.  Nothing introduces bugs faster than a tired programmer not 
realizing that he/she is inserting a statement in the target of one of 
these statements and thereby replacing the target with a new one.  This one 
issue has broken more patches in my experience than any other single item.

The argument that "this introduces a blizzard of unnecessary braces" is 
overweighed by the guarantee that the programming coming down the pike 
later won't accidentally remove a target line because s/he is too tired or 
rushed to recognize that s/he has to ADD BRACES (and in the case of a 
severely nested statement where to add braces) in order to turn a 
single-line target into a two-line target.  (Of course, some of you never 
make mistakes like that.  Fine.)

6)  When you have an "empty" statement as the compound statement, indicate 
it unambiguously.  I have yet to find a see compiler that doesn't handle 
the following construct correctly:

      while (wait_for_condition())
         {}

(or, more in keeping with Linus' style without adding an extra line, "while 
(wait_for_condition()) {}" )

The "{}" signal (familiar to those of you who are adept with xargs) 
indicates that nothing is being done, and does it far more readily than a 
single semicolon can ever signal.  If I could make just one change to the C 
language, I would REQUIRE that a non-empty statement or possibly empty 
compound statement be the only valid targets for if, else, do while, for, 
and while statements.

7)  Name space pollution is always a problem, although in these days of 
computer with gigabytes of RAM it's less of a problem than it used to 
be.  I started programming C when my main computer had 256K of RAM and the 
symbol table space for linking was limited.  I got in the habit of using 
structures to minimize the number of symbols I exposed. It also 
disambiguates local variables and parameters from file- and program-global 
variables.  This name-space management ensures that you don't accidentally 
redefine in an inner block a variable that you think is a global.  In very 
large programs, it also avoids name collisions between portions of the project.

Style has little to do with art.  Style has to do with minimizing mistakes, 
both now and down the road.  If you don't like what I do, then don't do 
what I do.  Do what minimizes mistakes for you.

And, Linus, I'm not recommending you adopt any of these suggestions -- you 
have your way and I have mine.  If you like any of these, though, feel free 
to take them for your own.  File off the serial numbers, and enjoy.

Stephen Satchell

-
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/

Re: [OT?] Coding Style

[Richard B. Johnson]

On Mon, 22 Jan 2001, Larry McVoy wrote:

> On Mon, Jan 22, 2001 at 11:04:50AM -0500, Jonathan Earle wrote:
> > > -----Original Message-----
> > > From: profmakx.fmp [mailto:profmakx.fmp@gmx.de]
> > > 
> > > So, every good programmer
> > > should know where to put comments. And it is unnecessary to 
> > > put comments to
> > > explain what code does. One should see this as stated in the 
> > > CodingStyle doc.
> > > Ok, there are points where a comment is good, but for example 
> > > at university
> > > we are to comment on every single line of code ...
> > 
> > WRONG!!!
> > 
> > Not documenting your code is not a sign of good coding, but rather shows
> > arrogance, laziness and contempt for "those who would dare tamper with your
> > code after you've written it".  Document and comment your code thoroughly.
> > Do it as you go along.  I was also taught to comment nearly every line - as
> > part of the coding style used by a large, international company I worked for
> > several years ago.  It brings the logic of the programmer into focus and
> > makes code maintenance a whole lot easier.  It also helps one to remember
> > the logic of your own code when you revisit it a year or more hence.
> 
> Please don't listen to this.  The only place you really want comments is
> 
>     a) at the top of files, describing the point of the file;
>     b) at the top of functions, if the purpose of the function is not obvious;
>     c) in line, when the code is not obvious.
> 
> If you are writing code that requires a comment for every line, you are 
> writing bad, obscure, unobvious code and no amount of commenting will fix
> it.
> 
> The real reason to sparing in your comments is that code and comments are
> not semantically bound to each other: the program doesn't stop working when
> the comment becomes incorrect.  It's incredibly frustrating to read a comment,
> believe you understand what is going on, only to find out that the comment
> and the code no longer match.   
> -- 
> ---
> Larry McVoy            	 lm at bitmover.com           http://www.bitmover.com/lm 


Okay, I'll byte (sic)...

If you are a good programmer, your code should work well and
you will be writing code for new projects long before the product
enters the in-production maintenance phase. This phase exists in
real products during their lifetime. At this time, rather junior
programmers will be required to add new capability or even fix
bugs.

Even excellent programmers generate bugs that are not discovered
for a long time (perhaps ever). This occurs because not every code
path gets tested so these bugs are not always found. For instance,
the return value from a function that encounters hardware errors may
not be correct because, during the entire development phase, the
hardware never generated that specific error.

When maintaining code, the programmer may have never seen the
code before. If it takes several weeks to find the function that
is returning the wrong value, and if it takes several hours to
correct the problem after the function is located, then the
original writer did not complete his or her job correctly.

Comments should assume that the reader is expert in the language
being used. No other assumptions produce useful documentation.

There are many ways to document code. Not all of these ways involve
comments. Examples are:

(1)	MACROS:

Lots of programmers don't use MACROS for documentation. However they
are very useful. Suppose we have a complicated single-bit sequence
necessary to communicate with a SEEPROM. If the main-line code does:

	WRITE_SEEPROM(parameter);
	READ_SEEPROM(parameter);

... then the code is very clear. The MACRO can be very complicated.
When it is isolated in this manner, the code both for the MACRO and
the functions that expand this MACRO are better documented than
just laying code. 

(2)	Descriptive names:

I don't like these myself. Often programmers get too cute. You
can look at the BusLogic code and see what I am talking about.
Practically every variable and function name begins with "BusLogic".

However, descriptive variable and function names do help document code.
This, even though many get carried away with extremes.

Most everybody will recognize:

	for (i=0; i< LIMIT; i++)
              ;

We don't really need:

	for(SimpleIntegerCount=0; SimpleIntegerCount < OneLessThanTheArraySize;
	    SimpleIntegerCount++)
               ;

But, when you are writing complicated code, it is often useful to use
descriptive names that uniquely define several otherwise similar routines.
For instance:

	Write_error_log(data);
	Append_error_log(data);

Again, some carry this to the extreme, they take a good idea and corrupt
it, MicroSoftSyle, into:

	WriteErrorLog(data);
	AppendErrorLog(data);

(3)	Comments:

Comments are very useful if they convey useful information. Many comments
are not useful because they seem to exist only because somebody made a
rule that said; "You have to comment your code...".

	An example:

	fprintf(stderr,"Memory allocation error\n");  /* No memory available */

Generally, comments should tell what is being done. The code tells how it's
being done.

For instance:
        value = 0;
	write_csr(value)      /* Need to synchronize */
	value |= SYNC;        /* This is really a 'start' bit */
        write_csr(value);
 

(4)	Constants:

Many constants are put into a header file or, worse, just scattered
throughout the code. These constants may represent hardware bits or
register contents that require some kind of explanation. Code that
does "magic", because of some number, is not well documented.

For instance:

	if(status & 0x80)
            do_something();

This should read:

	if(status & DATA_AVAILABLE)
            do_something();

In the second case, somebody took the time to figure out all the
status bits and define them somewhere. Now you don't have to do this.

Summing up, comments are only a small part of the total documentation
story. It is probably possible to write documented code without a
single comment. However, most of us are not quite that smart and
require a few comments here and there. Also, comments help you get
through Design Reviews, required if you write code that could impact
public safety.


Cheers,
Dick Johnson

Penguin : Linux version 2.4.0 on an i686 machine (799.53 BogoMips).

"Memory is like gasoline. You use it up when you are running. Of
course you get it all back when you reboot..."; Actual explanation
obtained from the Micro$oft help desk.


-
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/

RE: [OT?] Coding Style

[Jonathan Earle]

> -----Original Message-----
> From: Larry McVoy [mailto:lm@bitmover.com]
> 
> On Mon, Jan 22, 2001 at 11:04:50AM -0500, Jonathan Earle wrote:
> > > -----Original Message-----
> > > From: profmakx.fmp [mailto:profmakx.fmp@gmx.de]
> > > 
> > > So, every good programmer
> > > should know where to put comments. And it is unnecessary to 
> > > put comments to
> > > explain what code does. One should see this as stated in the 
> > > CodingStyle doc.
> > > Ok, there are points where a comment is good, but for example 
> > > at university
> > > we are to comment on every single line of code ...
> > 
> > WRONG!!!
> > 
> > Not documenting your code is not a sign of good coding, but 
> rather shows
> > arrogance, laziness and contempt for "those who would dare 
> tamper with your
> > code after you've written it".  Document and comment your 
> code thoroughly.
> > Do it as you go along.  I was also taught to comment nearly 
> every line - as
> > part of the coding style used by a large, international 
> company I worked for
> > several years ago.  It brings the logic of the programmer 
> into focus and
> > makes code maintenance a whole lot easier.  It also helps 
> one to remember
> > the logic of your own code when you revisit it a year or more hence.
> 
> Please don't listen to this.  The only place you really want 
> comments is
> 
>     a) at the top of files, describing the point of the file;
>     b) at the top of functions, if the purpose of the 
> function is not obvious;
>     c) in line, when the code is not obvious.
> 
> If you are writing code that requires a comment for every 
> line, you are 
> writing bad, obscure, unobvious code and no amount of 
> commenting will fix
> it.

The point of comments is not to "fix" bad code, it's to provide
understanding.  As the original poster said, _you_ may understand your code,
but that in no way implies that _I_ will, or your co-worker down the hall
will, etc.  I'm not suggesting that a statement like "counter=0;" at the
start of a function be commented, but other operations should be.  "Why do
we want this file written in /proc - wouldn't syslog have worked better?"
"Why is this loop skipping the first seven elements?"  "Why is this
structure used here instead of a simple array?"  "What on earth does
m->n->o->num represent?"

> The real reason to sparing in your comments is that code and 
> comments are
> not semantically bound to each other: the program doesn't 
> stop working when
> the comment becomes incorrect.  It's incredibly frustrating 
> to read a comment,
> believe you understand what is going on, only to find out 
> that the comment
> and the code no longer match.   

Comments should be updated when code is updated.  I believe that
documentation is of far greater value than code itself.  Code can be
changed, however, logic drives the code.  Without a good understanding of
the latter, the former is of little value, IMHO.

Cheers!
Jon
-
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/

Re: [OT?] Coding Style

[Gregory Maxwell]

On Mon, Jan 22, 2001 at 11:04:50AM -0500, Jonathan Earle wrote:
> WRONG!!!
> 
> Not documenting your code is not a sign of good coding, but rather shows
> arrogance, laziness and contempt for "those who would dare tamper with your
> code after you've written it".  Document and comment your code thoroughly.
> Do it as you go along.  I was also taught to comment nearly every line - as
> part of the coding style used by a large, international company I worked for
> several years ago.  It brings the logic of the programmer into focus and
> makes code maintenance a whole lot easier.  It also helps one to remember
> the logic of your own code when you revisit it a year or more hence.

Not wrong: You should document the interface, and any strange gotchas that
you faced while writing the function (like hardware bugs, etc). Then, if the
next person can't understand the code by reading it:

1. He's not qualified to change it.
*OR*
2. The code is crap, it needs to be rewritten anyways, good interface
documentation makes that possible.

Documenting every detail just encourages people with a paper thin
understanding to go and foul it up in subtile ways, it's better that they be
completely clueless and screw it up obviously.

Good code is simple, clean, and obvious. Sometimes, some code can't be clean
because it's facing a very hard problem, all the more reason to leave it to
gurus. 

-
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/

Re: [OT?] Coding Style

[Mark I Manning IV]

Stephen Satchell wrote:
> 
> One goal of language designers is to REMOVE the need for comments.  With a

this is a crock of (deleted).  You are chaising rainbows dood, you will
NEVER remove teh need for comments but its obvious you remove teh
comments.

> good fourth-generation or fifth-generation language, the need for comments
> diminishes to a detailed description of the data sets and any highly
> unusual operations or transforms on the data.

sorry but i could not disagree more

> 
> I've even gone so far as to "invent" my own languages, and the parsers to
> go with them, to reduce the need to comment by making the code easy for
> humans to read.  Not only are such systems easier to debug (with good
> language design) but are highly maintainable and usually not all that
> difficult to extend when necessary.

no lprogramming anguage can describe describe the design of the
applications written in it.  you NEED to comment your code.  100% Self
commenting code is a falacy.  50% self commenting code is almost
impossible to achieve.  COMMENT IT!

> 
> Remember, the line-by-line commenting requirement was mandatory in
> assembler programming, because the nature of assembler made you outline
> each step by tiring step.  

You talk like you dislike assembler as much as i dislike c :)


>                           When I worked for Rockwell, I was granted a
> partial wavier when I showed them my assembler-language commenting
> style:  pseudo-code at the top of each block of assembler code.

very ugly.  The S4 meter from landys and gyr (now siemens) actually uses
c code above each assembler routine as a form of commeting.  using code
to comment code is fine as long as you COMMENT the comments!

 
> Comments do NOT make code maintenance easier.  Too many comments obscure
> what is really going on. 

well... i disagree, years of consulting work and having to deal with
hunks of legacy code with no comments and huge functions etc etc et
(every coders worst nightmare) has taught me that comments are very much
needed (even bad comments are preferable to none at all)

> Linus' style actually increases the
> maintainability of the code, because if the code doesn't accurately show
> how it implements the goal specified in the block comment, the coder hasn't
> done his/her job.

TRUE.  Code should be written well enough that it isnt naturally
obfuscated but this does NOT remove the need for comments.

 
> Want to improve the maintainability of C code?  Consider the following:
> 
> 1)  Keep functional parts small.  If the code won't fit in a hundred lines
> or so of code, then you haven't factored the problem well
> enough.  Functional parts != functions.  

> A program with thousands of
> well-encapsulated function parts strung together into a single function is
> easier to maintain than a "well-factored" program with its parts spread all
> over hell.  

Cram a gazillion simple operations into a single function and you end up
with chaos, totally unfactored code is almost impossible to read.

> Diagnostic programmers have learned the hard way that factoring
> a program can make it difficult to ensure test coverage and even more
> difficult to determine if a part of the code is buggy or whether it found a
> hardware error that it was looking for. 

then they dont know how to test a program.  period


> In my ANSI C code, you will see the following a lot:
> 
> #define DO /*syntactic sugar */
> 
>      DO {
>         </* first functional part, with owned variables */
>      }
> 
>      DO {
>          </* next functional part, with its owned variables */
>      }
> 

> 
> 2)  Reduce visual complexity where possible.  Instead of using nested
> if-then-else statements, consider unrolling the nested
> statement.  Example:  {if (a && c)...; if (b && c)...; instead of {if (c)
> {if (a)...; if(b)...;}

which is simpler...

  (x + y) ^ 2 

or...

  (x ^2) + (Y ^2) + 2xy


> 3)  Make creative use of a run-on if statement to improve error detection
> and recording.  One of my tricks is to code the following statement in
> application programs:
> 
>       if(   (err = "input file can't be opened", in = fopen(filename,
> "rb"), in == NULL)
>         ||  (err = "output file can't be opened", out = fopen(oname, "wb"),
> out = NULL)
>         ...
>           )

use clever little tricks in your c so as to confuse people ?  You are
obviously a very advanced c coder who knows well the intracasies of the
language.  The person who has to maintain your code 10 years after you
have left may not be.

>        {
>        /* report the error that occurred, using the char * variable "err"
> to indicate the exact error. */
>        }

granted, the above block of code was not that difficult to understand,
even tho I have never seen that particular trick used before but the
above statement still stands. (nice trick btw :)
 
> 4)  The functional part should be contained in a reasonable number of
> lines.  Large while and for loops should call functions instead of having
> bloated bodies.  Large case statements should call functions instead of
> running on and on and on.

i wish everyone understood this (not usually a failing within the linux
kernel but you should see some of the code I have had to deal with. doh!
:)

 
> 5)  For those statements that take compound statements (if, else, while,
> for, do while) the statement should ALWAYS be a compound
> statement.  Nothing introduces bugs faster than a tired programmer not
> realizing that he/she is inserting a statement in the target of one of
> these statements and thereby replacing the target with a new one.  This one
> issue has broken more patches in my experience than any other single item.

by always adding braces to your if/else statements etc the above becomes
alot simpler me thunks... -->
 
> The argument that "this introduces a blizzard of unnecessary braces" is
> overweighed by the guarantee that the programming coming down the pike
> later won't accidentally remove a target line because s/he is too tired or
> rushed to recognize that s/he has to ADD BRACES (and in the case of a
> severely nested statement where to add braces) in order to turn a
> single-line target into a two-line target.  (Of course, some of you never
> make mistakes like that.  Fine.)

erm something is wrong here, i am actually agreeing with this guy ???
erm i think i need to go lie down for a while, i dont feel so good :)

> 6)  When you have an "empty" statement as the compound statement, indicate
> it unambiguously.  I have yet to find a see compiler that doesn't handle
> the following construct correctly:
> 
>       while (wait_for_condition())
>          {}


       while ( ... )	// is good but the above looks much nicer
         ;

 
> (or, more in keeping with Linus' style without adding an extra line, "while
> (wait_for_condition()) {}" )
       
this i dislike, ites easy for the eye to pass over the {} but STILL not
quite as bad as...

    while ( ..... );		// yukk :)


> 7)  Name space pollution is always a problem, although in these days of
> computer with gigabytes of RAM it's less of a problem than it used to
> be.  

well ok... less of a problem for the COMPUTER :)

>   I started programming C when my main computer had 256K of RAM and the
> symbol table space for linking was limited.  

should have been coding asm :)

>                                              I got in the habit of using
>  structures to minimize the number of symbols I exposed. It also
> disambiguates local variables and parameters from file- and program-global
> variables.  

explain this one to me, i think it might be usefull...

> Style has little to do with art.  Style has to do with minimizing mistakes,
> both now and down the road.  If you don't like what I do, then don't do
> what I do.  Do what minimizes mistakes for you.

style can show your art though, no style usually means no art :)
-
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/

Re: [OT?] Coding Style

[Larry McVoy]

On Mon, Jan 22, 2001 at 11:04:50AM -0500, Jonathan Earle wrote:
> > -----Original Message-----
> > From: profmakx.fmp [mailto:profmakx.fmp@gmx.de]
> > 
> > So, every good programmer
> > should know where to put comments. And it is unnecessary to 
> > put comments to
> > explain what code does. One should see this as stated in the 
> > CodingStyle doc.
> > Ok, there are points where a comment is good, but for example 
> > at university
> > we are to comment on every single line of code ...
> 
> WRONG!!!
> 
> Not documenting your code is not a sign of good coding, but rather shows
> arrogance, laziness and contempt for "those who would dare tamper with your
> code after you've written it".  Document and comment your code thoroughly.
> Do it as you go along.  I was also taught to comment nearly every line - as
> part of the coding style used by a large, international company I worked for
> several years ago.  It brings the logic of the programmer into focus and
> makes code maintenance a whole lot easier.  It also helps one to remember
> the logic of your own code when you revisit it a year or more hence.

Please don't listen to this.  The only place you really want comments is

    a) at the top of files, describing the point of the file;
    b) at the top of functions, if the purpose of the function is not obvious;
    c) in line, when the code is not obvious.

If you are writing code that requires a comment for every line, you are 
writing bad, obscure, unobvious code and no amount of commenting will fix
it.

The real reason to sparing in your comments is that code and comments are
not semantically bound to each other: the program doesn't stop working when
the comment becomes incorrect.  It's incredibly frustrating to read a comment,
believe you understand what is going on, only to find out that the comment
and the code no longer match.   
-- 
---
Larry McVoy            	 lm at bitmover.com           http://www.bitmover.com/lm 
-
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/

Re: [OT?] Coding Style

[Mike Harrold]

> 
> > -----Original Message-----
> > From: profmakx.fmp [mailto:profmakx.fmp@gmx.de]
> > 
> > So, every good programmer
> > should know where to put comments. And it is unnecessary to 
> > put comments to
> > explain what code does. One should see this as stated in the 
> > CodingStyle doc.
> > Ok, there are points where a comment is good, but for example 
> > at university
> > we are to comment on every single line of code ...
> 
> WRONG!!!
> 
> Not documenting your code is not a sign of good coding, but rather shows
> arrogance, laziness and contempt for "those who would dare tamper with your
> code after you've written it".  Document and comment your code thoroughly.
> Do it as you go along.  I was also taught to comment nearly every line - as
> part of the coding style used by a large, international company I worked for
> several years ago.  It brings the logic of the programmer into focus and
> makes code maintenance a whole lot easier.  It also helps one to remember
> the logic of your own code when you revisit it a year or more hence.
> 

There is an old programmer's rule.

"Documentation? Too bad. If the code was damned hard to write, it should
be damned hard to understand."

:)

/Mike
-
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/

RE: [OT?] Coding Style

[Jonathan Earle]

> -----Original Message-----
> From: profmakx.fmp [mailto:profmakx.fmp@gmx.de]
> 
> So, every good programmer
> should know where to put comments. And it is unnecessary to 
> put comments to
> explain what code does. One should see this as stated in the 
> CodingStyle doc.
> Ok, there are points where a comment is good, but for example 
> at university
> we are to comment on every single line of code ...

WRONG!!!

Not documenting your code is not a sign of good coding, but rather shows
arrogance, laziness and contempt for "those who would dare tamper with your
code after you've written it".  Document and comment your code thoroughly.
Do it as you go along.  I was also taught to comment nearly every line - as
part of the coding style used by a large, international company I worked for
several years ago.  It brings the logic of the programmer into focus and
makes code maintenance a whole lot easier.  It also helps one to remember
the logic of your own code when you revisit it a year or more hence.

Jon
-
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/