Reply to post: He's being fairly tolerant on this apparently

Linus Torvalds in sweary rant about punctuation in kernel comments

Gary Bickford

He's being fairly tolerant on this apparently

In my experience most groups have a defined acceptable style that is pretty strict, not a group of styles that are acceptable. In every case the group insists on using that style, period, no exceptions and code reviews include this aspect. For my part, having settled on using Doxygen for auto doc system, I've been using a tweaked set of Vim scripts that build the comment structures automatically so at least the form is there.

In line documentation is a place where the 'principle of least surprise' applies. It is important for code readers to be able to scan quickly and absorb the essence without having to interpret unfamiliar comment layouts. This is similar to how drivers may have difficulty interpreting road signs when first driving in a new location that has different signage conventions. If variable declarations are _always_ precede by a comment description, even if it is empty, then the eye picks each variable up and now knows about it.

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