Dear Nico,
Thank you for taking this up again. Am Samstag, den 28.01.2017, 15:00 +0100 schrieb Nico Huber: > > sorry to revive this old, stale topic. I got stalled by a request to > ensure the comment style with a script. Now, that I had a look at > checkpatch.pl, I don't think this could be done easily without risking > many false positives. > > So I'm again asking to commit my proposal below. I've incorporated the > comments from Martin. Just to be clear, also for the proposal below, the style can’t be checked, right? > Even if it's not going to be my preferred style, I would really appre- > ciate it if we could agree on one style. > > Nico > > > == 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 complex 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. > > > > coreboot style for comments is the C89 "/* ... */" style. You may also > > use C99-style "// ..." comments. Could we change that, C89 style comments are preferred, and add a note about consistency? > … You may also use C99 style "// …" comments, if it’s beneficial. > Also, the commenting should be consistent in one file. Or is that wishful thinking, and both style will always be mixed? > > The preferred style for concise multi-line comments that explain a > > single piece of code is: Please, emphasize *concise*, or elaborate right away with *i. e., one paragraph* > > > > /* This is the preferred style for > > two or three line comments that > > avoids excessive blank lines. */ > > > > Note that there shouldn't be leading asterisks on new lines in the > > concise style. > > > > The preferred style for long multi-line comments is: Please emphasize *long*. > > /* > > * This is the preferred style for multi-line > > * comments in the coreboot source code. > > * > > * Description: A column of asterisks on the left side, > > * with beginning and ending almost-blank lines. > > */ > > > > Some rules of thumb to decide which style to use: > > * If you are commenting a whole function (indentation level 0) or > > something high level (indentation level 1), use the long style. > > * If you want to explain a single piece of code and your comment > > doesn't span multiple paragraphs, use the concise style. > > * Otherwise you might want to ask yourself why what you're going to > > explain doesn't deserve an own function. > > > > It's also important to comment data, whether they are basic types or > > derived types. To this end, use just one data declaration per line (no > > commas for multiple data declarations). This leaves you room for a > > small comment on each item, explaining its use. > > > > If the author has reasonable arguments for breaking the recommended > > style guide to improve readability, others should be respectful of those > > differences. Nico, thank you again. Thanks, Paul
signature.asc
Description: This is a digitally signed message part
-- coreboot mailing list: [email protected] https://www.coreboot.org/mailman/listinfo/coreboot
