On 06.09.2016 00:04, Vadim Bendebury wrote: > On Sun, Sep 4, 2016 at 7:42 AM, Nico Huber <[email protected]> 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: [email protected] https://www.coreboot.org/mailman/listinfo/coreboot
