Comment guidelines conflict with Comment Tips from the Elisp reference

[swsnr]

Tthe rule to use three semicolons for top-level comments conflicts with the Emacs Lisp reference.

According to Comment Tips two semicolons should be used for top-level comments between functions:

Comments that start with two semicolons, ‘;;’, should be aligned to the same level of indentation as the code. […] We also normally use two semicolons for comments outside functions.

Three semicolons are used for headings (emphasis mine):

Comments that start with three semicolons, ‘;;;’, should start at the left margin. […] We also use them sometimes for comments that are between functions—whether to use two or three semicolons depends on whether the comment should be considered a “heading” by Outline minor mode. By default, comments starting with at least three semicolons (followed by a single space and a non-whitespace character) are considered headings, comments starting with two or fewer are not.

That's also the style used within Emacs, for instance in font-lock.el.

I do not think that we should deviate from the Emacs Lisp references without need.

[swsnr]

Besides, comments in Emacs seem use two spaces between sentences, generally, and I think we should stick to that. I know that two-spacing is typographically wrong, but code is not typography, and two spaces are easier to read, imho, since the make a clear difference between end-of-sentence punctuation, and other punctation, e.g. after abbreviations, especially in monospace fonts.

[bbatsov]

Definitely! I never noticed this section in the reference (the current comments examples are derived from a Scheme style guide).

[bbatsov]

P.S. I quickly drafted something, just so I could kick-off the project and invite others to join (I'm fairly sure I've made some mistakes here and there).

[swsnr]

Besides, the single-space rule for end of sentences won't work with the default Emacs settings: sentence-end-double-space is non-nil by default.

[Malabarba]

On this last point about sentences:
I'd rather not incentivise double-space sentences just because it's the default value of a variable, even if it does seem to be used in some emacs files (font-lock.el is one).

If there's a case against single-space, then perhaps the guide should abstain from that argument. But double-space just looks wrong to a lot of people.

[swsnr]

@Bruce-Connor Emacs' own source uses two spaces mostly. Actually, I grepped it and there's just a single subsystem that opts out of this by setting sentence-end-double-space to nil in file local variables.

Emacs' own source is the authoritative reference for Emacs Lisp, and it predates this style guide by decades.

I don't think that “looks wrong [to me]” is strong enough a reason to break with Emacs. We have neither the authority nor the standing to do so.

So in my opinion, the style guide should either mandate two spaces at sentence end, nor not mention it at all.

[Malabarba]

Indeed, I did recognize it was used in emacs files. :-)

When I said it looked wrong to a lot of people, I wasn't just basing on personal opinion, but on (well-based) recommendations I've read and gathered in the past in regards to writting prose. A simple google search will show I'm not the only one.

Don't worry, I'm not saying the opinions of the internet should be a holy guide. You're right that emacs own source should trump readability considerations. I just voiced a few points I thought were relevant, regardless of the final outcome. I won't fight for them or anything. :-)