Page MenuHomeFreeBSD

Document the convention of adding a blank line before comments.
AcceptedPublic

Authored by markj on Sep 25 2019, 4:01 PM.

Details

Reviewers
kevans
cem
kib
jhb

Diff Detail

Lint
Lint OK
Unit
No Unit Test Coverage
Build Status
Buildable 26718
Build 25078: arc lint + arc unit

Event Timeline

markj created this revision.Sep 25 2019, 4:01 PM
cem accepted this revision.Sep 25 2019, 4:13 PM

Bump .Dd before commit, of course.

This revision is now accepted and ready to land.Sep 25 2019, 4:13 PM
kevans accepted this revision.Sep 25 2019, 4:41 PM
kib added a comment.Sep 25 2019, 6:43 PM

I was told by bde (?) that after the block of code that is described by the multi-line comment, there should be a blank line. Since you carefully document other moments, this one should be described as well, I believe.

markj updated this revision to Diff 62601.Sep 26 2019, 4:16 PM

Address kib's feedback.

This revision now requires review to proceed.Sep 26 2019, 4:16 PM
cem accepted this revision.Sep 26 2019, 4:57 PM

I don't know if this update is a hard and fast style rule, but it makes sense to me in contexts like the written example. IMO, people shouldn't take it too literally — for example, if the code described is at the end of a block using }, you don't necessarily need a blank line to delineate scope, because the } line ends the scope neatly.

(If your block is a single statement and lacks {/}, and has a multi-line comment, maybe it should add {/} rather than a blank line. I don't feel the need to codify that in style.9.)

This revision is now accepted and ready to land.Sep 26 2019, 4:57 PM
kib accepted this revision.Sep 26 2019, 5:15 PM