all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Conventions for writing comments
@ 2014-10-06  9:20 Sebastien Vauban
  2014-10-06 13:09 ` Stefan Monnier
  0 siblings, 1 reply; 4+ messages in thread
From: Sebastien Vauban @ 2014-10-06  9:20 UTC (permalink / raw)
  To: emacs-devel-mXXj517/zsQ

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




^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Conventions for writing comments
  2014-10-06  9:20 Conventions for writing comments Sebastien Vauban
@ 2014-10-06 13:09 ` Stefan Monnier
  2014-10-06 15:06   ` Sebastien Vauban
  0 siblings, 1 reply; 4+ messages in thread
From: Stefan Monnier @ 2014-10-06 13:09 UTC (permalink / raw)
  To: Sebastien Vauban; +Cc: emacs-devel

> 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



^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Conventions for writing comments
  2014-10-06 13:09 ` Stefan Monnier
@ 2014-10-06 15:06   ` Sebastien Vauban
  2014-10-06 16:31     ` Stefan Monnier
  0 siblings, 1 reply; 4+ messages in thread
From: Sebastien Vauban @ 2014-10-06 15:06 UTC (permalink / raw)
  To: emacs-devel-mXXj517/zsQ

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




^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: Conventions for writing comments
  2014-10-06 15:06   ` Sebastien Vauban
@ 2014-10-06 16:31     ` Stefan Monnier
  0 siblings, 0 replies; 4+ messages in thread
From: Stefan Monnier @ 2014-10-06 16:31 UTC (permalink / raw)
  To: Sebastien Vauban; +Cc: emacs-devel

>>> - 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



^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2014-10-06 16:31 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-10-06  9:20 Conventions for writing comments Sebastien Vauban
2014-10-06 13:09 ` Stefan Monnier
2014-10-06 15:06   ` Sebastien Vauban
2014-10-06 16:31     ` Stefan Monnier

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.