Consider adding a "comment formatting" guide

[astrieanna]

This is just a suggestion, based on something I liked at Google:

Block comments should be separated from the # by a space. Inline comments should be separated from the preceding code by two spaces, and from the # by one space. All comments should be written as full sentences. If an inline comment is just a phrase, it should still start with a capital letter and end with a period. (Variable/etc names in comments should keep their actual capitalization, even at the start of a comment.)

Good style:

# Block comment, like for commenting on what a function does,
# or what a module contains or a script does or whatever.
# Wrap at 80 characters (or whatever line limit you're using)

x = 5  # This is an inline comment.

[johnmyleswhite]

I fully agree with this proposal. Since my long-term goal is to see something like juliafmt get written, I think we should try to keep two parts of this proposal separate:

• The rules about spaces, which are easy to enforce programmatically.
• The English grammar rules, which are hard to enforce programmatically.

I'm happy to adopt both, but we can only hope to enforce rules that don't depend upon natural language processing technologies.