Re: [coreboot] Proposal for new "Commenting" wiki text (was: [RFC] Deciding on style for multi-line comments)
Hi folks,
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.
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.
The preferred style for concise multi-line comments that explain a single piece of code is:
/* 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:
/* * 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.
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
-
Nico Huber -
Paul Menzel