Coding Style
A message that is not in the archive (sent off-list or not yet received): [email protected]
Quoted 3 lines · Mark I Manning IV
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".
Quoted 4 lines
Quoted 2 lines
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.
Quoted 3 lines
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 [email protected]
Please read the FAQ at http://www.tux.org/lkml/
Quoted 25 lines · Anton Altaparmakov
Quoted 1 line · Linus Torvalds
On Fri, 19 Jan 2001, Mark I Manning IV wrote:
[snip]
Quoted 11 lines
Quoted 1 line
Quoted 1 line
And two spaces is not enough. If you write code that needs
comments at
Quoted 3 lines
Quoted 1 line
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]
Quoted 2 lines
Notice? Not AFTER the statements.
Quoted 8 lines
Quoted 3 lines
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 [email protected]
Please read the FAQ at http://www.tux.org/lkml/