Reply to post:

Linus Torvalds in sweary rant about punctuation in kernel comments

Charles 9 Silver badge

"For comments on lines of code, I prefer to use the double slash.

For block comments I generally have a slash followed by a line of asterisks, followed by one or more lines of text (no asterisks), followed by a line of asterisks ending in a slash. Separates the block visually, nice symmetry, easy to edit."

That's my style, too, and I tend to keep a certain structure. Each section of code (declarations, definitions, etc.) I use a simple block comment: Line, Section name in all caps, Line. Functions I use a detailed block quote that spells out what it's supposed to do, what goes in, what comes out.

And the reason I use lots of comments is because I realize different people think in different ways. The path of logic I took to get something done may not be the same one someone else uses, and as result following actual code can sometimes derail people simply due to different experiences. Since I've personally had to go through the act myself with someone else's sparsely-commented code, I can speak from experience; it can be a slog, and many of us have deadlines. So the inline comments act like breadcrumbs to map out the paths within functions like the blocks act as signposts to show goals and other things in a broader sense.

POST COMMENT House rules

Not a member of The Register? Create a new account here.

  • Enter your comment

  • Add an icon

Anonymous cowards cannot choose their icon

Biting the hand that feeds IT © 1998–2019