Conventions for writing comments

Conventions for writing comments

[Sebastien Vauban]

Hello,

I have a small question about conventions for writing comments... Can
I consider the following to be the rule?

- If it's a *sentence* (like ";; Search for the first instance", in the
  imperative form), comments must begin with a capital and end with a dot.
  
- Otherwise (like ";; pattern found"), comments must begin with a small
  letter and don't end with a dot.

?

Tips on writing comments found on
https://www.gnu.org/software/emacs/manual/html_node/elisp/Comment-Tips.html
aren't very helpful regarding my question, as you see things such as:

- "; there was there was a base version to which this looks like
  a subversion", that is a sentence with no capital nor dot...

- ";; Update mode line.", that is a sentence with both beginning capital
  and to.

- ";;;; The kill ring", an expression with a capital...

Though, that page seems to be more on the usage of ";", ";;", ";;;" and
";;;;" than on the usage of capitals and dots.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Conventions for writing comments

[Stefan Monnier]

> I have a small question about conventions for writing comments... Can
> I consider the following to be the rule?

The main documentation we follow for coding style is the GNU Coding
Standard (https://www.gnu.org/prep/standards/html_node/Comments.html)
which says, among other things:

   Also, please write complete sentences and capitalize the first word.

> - Otherwise (like ";; pattern found"), comments must begin with a small
>   letter and don't end with a dot.

I prefer to capitalize and punctuate this as well (BTW: this is also
a sentence).  Note that a lot of code in Emacs does not follow the
convention, because we're not strict enough about enforcing it.


        Stefan

Re: Conventions for writing comments

[Sebastien Vauban]

Stefan Monnier wrote:
>> I have a small question about conventions for writing comments... Can
>> I consider the following to be the rule?
>
> The main documentation we follow for coding style is the GNU Coding
> Standard (https://www.gnu.org/prep/standards/html_node/Comments.html)
> which says, among other things:
>
>    Also, please write complete sentences and capitalize the first word.
>
>> - Otherwise (like ";; pattern found"), comments must begin with a small
>>   letter and don't end with a dot.
>
> I prefer to capitalize and punctuate this as well (BTW: this is also
> a sentence).

Interesting. I wouldn't have called that a sentence. For me, it should
be "pattern is found" or "pattern has been found" or such to become
a sentence. But that's out of the story, and the information is that,
for you, the conventions are that *all* comments must be treated the
same way. Thanks for the information.

Best regards,
  Seb

-- 
Sebastien Vauban

Re: Conventions for writing comments

[Stefan Monnier]

>>> - Otherwise (like ";; pattern found"), comments must begin with a small
>>> letter and don't end with a dot.
>> I prefer to capitalize and punctuate this as well (BTW: this is also
>> a sentence).
> Interesting. I wouldn't have called that a sentence.

Sorry, I was distracted, it's indeed just an exclamation.

> But that's out of the story, and the information is that, for you, the
> conventions are that *all* comments must be treated the same way.

That's right.
Of course, it matters about as much as the color of the shed.


        Stefan