Hi Wolfgang,
Wolfgang Mües wrote:
Hello Greg,
On Mittwoch, 25. Juli 2007, Greg Ungerer wrote:
And one style issue. Comments in the kernel should not be
c89/c++ style, don't use "//". See
linux-2.6.x/Documentation/CodingStyle.
I had a look:
Chapter 7: Commenting
What kernel version did you get this from?
Comments are good, but there is also a danger of over-commenting.
NEVER try to explain HOW your code works in a comment: it's much
better to write the code so that the _working_ is obvious, and it's a
waste of time to explain badly written code.
Generally, you want your comments to tell WHAT your code does, not
HOW. Also, try to avoid putting comments inside a function body: if
the function is so complex that you need to separately comment parts
of it, you should probably go back to chapter 5 for a while. You can
make small comments to note or warn about something particularly
clever (or ugly), but try to avoid excess. Instead, put the comments
at the head of the function, telling people what it does, and
possibly WHY it does it.
When commenting the kernel API functions, please use the kerneldoc
format. See the files Documentation/kernel-doc-nano-HOWTO.txt and
scripts/kernel-doc for details.
So can you please show me where Linus has disallowed the "//"?
Yes, from linux-2.6.22/Documentation/CodingStyle:
Chapter 8: Commenting
Comments are good, but there is also a danger of over-commenting. NEVER
try to explain HOW your code works in a comment: it's much better to
write the code so that the _working_ is obvious, and it's a waste of
time to explain badly written code.
Generally, you want your comments to tell WHAT your code does, not HOW.
Also, try to avoid putting comments inside a function body: if the
function is so complex that you need to separately comment parts of it,
you should probably go back to chapter 6 for a while. You can make
small comments to note or warn about something particularly clever (or
ugly), but try to avoid excess. Instead, put the comments at the head
of the function, telling people what it does, and possibly WHY it does
it.
When commenting the kernel API functions, please use the kernel-doc format.
See the files Documentation/kernel-doc-nano-HOWTO.txt and scripts/kernel-doc
for details.
Linux style for comments is the C89 "/* ... */" style.
Don't use C99-style "// ..." comments.
...
Regards
Greg
------------------------------------------------------------------------
Greg Ungerer -- Chief Software Dude EMAIL: [EMAIL PROTECTED]
Secure Computing Corporation PHONE: +61 7 3435 2888
825 Stanley St, FAX: +61 7 3891 3630
Woolloongabba, QLD, 4102, Australia WEB: http://www.SnapGear.com
_______________________________________________
uClinux-dev mailing list
[email protected]
http://mailman.uclinux.org/mailman/listinfo/uclinux-dev
This message was resent by [email protected]
To unsubscribe see:
http://mailman.uclinux.org/mailman/options/uclinux-dev
