Re: [coreboot] Proposal for new "Commenting" wiki text
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: coreboot@coreboot.org https://www.coreboot.org/mailman/listinfo/coreboot
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. -- coreboot mailing list: coreboot@coreboot.org https://www.coreboot.org/mailman/listinfo/coreboot
Re: [coreboot] Proposal for new "Commenting" wiki text (was: [RFC] Deciding on style for multi-line comments)
Dear Nico, Thank you for sending the proposal around. What ever is decided on, please make sure it can be automatically checked by the commit hooks, and that the scripts are updated in the repository at the same time the guidelines are changed. Thanks, Paul signature.asc Description: This is a digitally signed message part -- coreboot mailing list: coreboot@coreboot.org https://www.coreboot.org/mailman/listinfo/coreboot
Re: [coreboot] Proposal for new "Commenting" wiki text
On 05.09.2016 18:34, tmiket wrote: > On 2016-09-04 12:36, Martin Roth wrote: >> Hey Nico,Thanks for writing that up and not just letting this drop >> with no >> resolution and action. >> >> To anyone just coming in on the discussion, here's what we're talking >> about >> changing: >> https://www.coreboot.org/Coding_Style#Commenting > > I am new to this discussion and to coreboot. Welcome to coreboot, then :) > > This appears to be a "hidden" page in that the TOC on top left doesn't have > a link called Coding Style. Is this a new work in progress page? I wouldn't call it "hidden". As with most wikis, there is just no com- prehensive TOC. > > It appears more detailed than the corresponding Coding Style in the > Development Guidelines page. Actually, that page links to Coding_Style in section 2.5. But maybe we should link it on the Welcome page, too. Regards, Nico > > I'm asking because I start a new job that uses coreboot and I'm working > my way through the online documentation. > Cheers, > T.mike > >> >> I'd suggest just a couple of changes to your update: >> >> Let's define what a "short" comment is to avoid future arguments that >> 10 >> lines is short: >>> /* This is the preferred style for >>> two or three line comments that >>> avoids excessive blank lines. */ >> >> And I'm not certain of this paragraph, and I'd recommend removing or >> changing it a bit. >> >>> In case of doubt, the author of the code shall have the last word on >>> comment styles. He should know best which style makes his code most >>> readable. >> >> 1) I think that Stefan as the project leader should have the decision >> about >> anything that is controversial enough to need a last word. >> 2) What if the author is female? :) Maybe use 'they' as the pronoun >> if this >> >> paragraph is left in. Not a big deal, but I'd like to be inclusive. >> >> 3) I think this might be just asking for arguments. I'm not talking >> about anyone >> specific, just thinking of discussions in the past. >> -- "As the author I LIKE ascii art in my comments and I get the final >> say." >> -- We're going to get lawyer arguments: "It says above that the c99 >> style >> is valid - why can't we just prefix the whole 16 line block with >> '//'"? >> -- "I know it says not to say 'increment i', but as the author, I >> think it's >> helpful." >> 4) I think this would be the only "the author has the final say" >> policy - what >> happens when someone rewrites the comment in a following patch? Who >> is the author? >> >> Maybe we could change it from "has the last word" to something saying >> like: >> >>> If the author has reasonable arguments for breaking the recommended >>> style guide to improve readability, others should be respectful of >> those >>> differences. >> >> I think this preserves the intent without some of the issues. >> >> Martin >> >> On Sun, Sep 4, 2016 at 8:42 AM, Nico Huber wrote: >> >>> Hi folks, >>> >>> I think we kind of agreed that the wiki text about "Commenting" >>> should >>> change. So here is my proposal, feel free to edit, add something or >>> just >>> ack or complain about it. >>> == 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 shorter multi-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
Re: [coreboot] Proposal for new "Commenting" wiki text (was: [RFC] Deciding on style for multi-line comments)
On 06.09.2016 00:04, Vadim Bendebury wrote: > On Sun, Sep 4, 2016 at 7:42 AM, Nico Huber wrote: > >> Hi folks, >> >> I think we kind of agreed that the wiki text about "Commenting" should >> change. So here is my proposal, feel free to edit, add something or just >> ack or complain about it. >> >>> == 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 >>> shorter multi-line comments that >>> avoids excessive blank lines. */ >> > > why does the concise style have to be so different from the verbose style? > Lines starting with '* ' are easier identifiable as comments. Well, until now, there were only arguments against and none for the lea- ding asterisk. In [1] Linus calls it "visually unbalanced". And let me quote my argument: > But I'm really with Linus when it comes to the leading, single asterisk. > It looks totally weird, IMHO > > /* A small, concise comment > that doesn't fit a single line */ > > is easier for the eye than > > /* A small, concise comment >* that doesn't fit a single line */ > > where your eyes somehow stick on the asterisk first and then have to > search for the real start of the line. Nico [1] https://lkml.org/lkml/2016/7/8/625 > > --vb > > > > >>> >>> 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. >>> >>> In case of doubt, the author of the code shall have the last word on >>> comment styles. He should know best which style makes his code most >>> readable. >> >> Nico >> > -- coreboot mailing list: coreboot@coreboot.org https://www.coreboot.org/mailman/listinfo/coreboot
Re: [coreboot] Proposal for new "Commenting" wiki text (was: [RFC] Deciding on style for multi-line comments)
On 04.09.2016 21:36, Martin Roth wrote: > Hey Nico, > Thanks for writing that up and not just letting this drop with no > resolution and action. > > To anyone just coming in on the discussion, here's what we're talking about > changing: > https://www.coreboot.org/Coding_Style#Commenting > > > I'd suggest just a couple of changes to your update: > > Let's define what a "short" comment is to avoid future arguments that 10 > lines is short: >> /* This is the preferred style for >> two or three line comments that >> avoids excessive blank lines. */ > Sounds good. > > And I'm not certain of this paragraph, and I'd recommend removing or > changing it a bit. > >> In case of doubt, the author of the code shall have the last word on >> comment styles. He should know best which style makes his code most >> readable. > > 1) I think that Stefan as the project leader should have the decision about > anything that is controversial enough to need a last word. > 2) What if the author is female? :) Maybe use 'they' as the pronoun if > this > paragraph is left in. Not a big deal, but I'd like to be inclusive. > 3) I think this might be just asking for arguments. I'm not talking about > anyone > specific, just thinking of discussions in the past. > -- "As the author I LIKE ascii art in my comments and I get the final say." > -- We're going to get lawyer arguments: "It says above that the c99 style > is valid - why can't we just prefix the whole 16 line block with '//'"? > -- "I know it says not to say 'increment i', but as the author, I think > it's > helpful." > 4) I think this would be the only "the author has the final say" policy - > what > happens when someone rewrites the comment in a following patch? Who > is the author? > > Maybe we could change it from "has the last word" to something saying like: > >> If the author has reasonable arguments for breaking the recommended >> style guide to improve readability, others should be respectful of those >> differences. > > I think this preserves the intent without some of the issues. > Yes, that's much better. I just included that paragraph as I remembered something like "the author should know best" from the discussion. Thank you, Nico -- coreboot mailing list: coreboot@coreboot.org https://www.coreboot.org/mailman/listinfo/coreboot
Re: [coreboot] Proposal for new "Commenting" wiki text (was: [RFC] Deciding on style for multi-line comments)
On Sun, Sep 4, 2016 at 7:42 AM, Nico Huber wrote: > Hi folks, > > I think we kind of agreed that the wiki text about "Commenting" should > change. So here is my proposal, feel free to edit, add something or just > ack or complain about it. > > > == 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 > > shorter multi-line comments that > > avoids excessive blank lines. */ > why does the concise style have to be so different from the verbose style? Lines starting with '* ' are easier identifiable as comments. --vb > > > > 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. > > > > In case of doubt, the author of the code shall have the last word on > > comment styles. He should know best which style makes his code most > > readable. > > Nico > -- coreboot mailing list: coreboot@coreboot.org https://www.coreboot.org/mailman/listinfo/coreboot
Re: [coreboot] Proposal for new "Commenting" wiki text
On 2016-09-04 12:36, Martin Roth wrote: Hey Nico,Thanks for writing that up and not just letting this drop with no resolution and action. To anyone just coming in on the discussion, here's what we're talking about changing: https://www.coreboot.org/Coding_Style#Commenting I am new to this discussion and to coreboot. This appears to be a "hidden" page in that the TOC on top left doesn't have a link called Coding Style. Is this a new work in progress page? It appears more detailed than the corresponding Coding Style in the Development Guidelines page. I'm asking because I start a new job that uses coreboot and I'm working my way through the online documentation. Cheers, T.mike I'd suggest just a couple of changes to your update: Let's define what a "short" comment is to avoid future arguments that 10 lines is short: /* This is the preferred style for two or three line comments that avoids excessive blank lines. */ And I'm not certain of this paragraph, and I'd recommend removing or changing it a bit. In case of doubt, the author of the code shall have the last word on comment styles. He should know best which style makes his code most readable. 1) I think that Stefan as the project leader should have the decision about anything that is controversial enough to need a last word. 2) What if the author is female? :) Maybe use 'they' as the pronoun if this paragraph is left in. Not a big deal, but I'd like to be inclusive. 3) I think this might be just asking for arguments. I'm not talking about anyone specific, just thinking of discussions in the past. -- "As the author I LIKE ascii art in my comments and I get the final say." -- We're going to get lawyer arguments: "It says above that the c99 style is valid - why can't we just prefix the whole 16 line block with '//'"? -- "I know it says not to say 'increment i', but as the author, I think it's helpful." 4) I think this would be the only "the author has the final say" policy - what happens when someone rewrites the comment in a following patch? Who is the author? Maybe we could change it from "has the last word" to something saying like: If the author has reasonable arguments for breaking the recommended style guide to improve readability, others should be respectful of those differences. I think this preserves the intent without some of the issues. Martin On Sun, Sep 4, 2016 at 8:42 AM, Nico Huber wrote: Hi folks, I think we kind of agreed that the wiki text about "Commenting" should change. So here is my proposal, feel free to edit, add something or just ack or complain about it. == 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 shorter multi-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. In case of doubt, the author of the code shall have the last word on comment styles. He should know best which style makes his code most readable. Nico -- coreboot mailing list: coreboot@coreboot.org https://www.coreboot.org/mailman/listinfo/c
Re: [coreboot] Proposal for new "Commenting" wiki text (was: [RFC] Deciding on style for multi-line comments)
Hey Nico, Thanks for writing that up and not just letting this drop with no resolution and action. To anyone just coming in on the discussion, here's what we're talking about changing: https://www.coreboot.org/Coding_Style#Commenting I'd suggest just a couple of changes to your update: Let's define what a "short" comment is to avoid future arguments that 10 lines is short: > /* This is the preferred style for > two or three line comments that > avoids excessive blank lines. */ And I'm not certain of this paragraph, and I'd recommend removing or changing it a bit. > In case of doubt, the author of the code shall have the last word on > comment styles. He should know best which style makes his code most > readable. 1) I think that Stefan as the project leader should have the decision about anything that is controversial enough to need a last word. 2) What if the author is female? :) Maybe use 'they' as the pronoun if this paragraph is left in. Not a big deal, but I'd like to be inclusive. 3) I think this might be just asking for arguments. I'm not talking about anyone specific, just thinking of discussions in the past. -- "As the author I LIKE ascii art in my comments and I get the final say." -- We're going to get lawyer arguments: "It says above that the c99 style is valid - why can't we just prefix the whole 16 line block with '//'"? -- "I know it says not to say 'increment i', but as the author, I think it's helpful." 4) I think this would be the only "the author has the final say" policy - what happens when someone rewrites the comment in a following patch? Who is the author? Maybe we could change it from "has the last word" to something saying like: > If the author has reasonable arguments for breaking the recommended > style guide to improve readability, others should be respectful of those > differences. I think this preserves the intent without some of the issues. Martin On Sun, Sep 4, 2016 at 8:42 AM, Nico Huber wrote: > Hi folks, > > I think we kind of agreed that the wiki text about "Commenting" should > change. So here is my proposal, feel free to edit, add something or just > ack or complain about it. > > > == 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 > > shorter multi-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. > > > > In case of doubt, the author of the code shall have the last word on > > comment styles. He should know best which style makes his code most > > readable. > > Nico > -- coreboot mailing list: coreboot@coreboot.org https://www.coreboot.org/mailman/listinfo/coreboot
[coreboot] Proposal for new "Commenting" wiki text (was: [RFC] Deciding on style for multi-line comments)
Hi folks, I think we kind of agreed that the wiki text about "Commenting" should change. So here is my proposal, feel free to edit, add something or just ack or complain about it. > == 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 > shorter multi-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. > > In case of doubt, the author of the code shall have the last word on > comment styles. He should know best which style makes his code most > readable. Nico -- coreboot mailing list: coreboot@coreboot.org https://www.coreboot.org/mailman/listinfo/coreboot
