Improve treatment of comments

[mjrusso]

There are several issues with the way that the style guide currently describes how comments should be written. In general, a literate programming style is encouraged (but certainly not mandated). However, the current guide is not compatible with said literate programming style.

The following is a summary of issues as logged by @jashkenas, moved here from ticket #2:

---

Ideally, improve the code to obviate the need for the
comment, and delete the comment entirely.

Actually, CoffeeScript tries to encourage pervasive commenting ... not so much to answer the "what" or the "how" of any individual line of code, but to answer the "why".

If a comment is short, the period at the end can be omitted.

Nope -- comments should be written as full sentences, with proper punctuation.

---

The bit that you describe as "block comments" aren't CoffeeScript block comments, which look like this:

###
comment
###

... but, the ones that you describe are always preferred instead of block comments -- which should only be used if you intend to pass along the comment to the underlying JS, like a license, or warning.

---

The use of inline comments should be limited, because their existence is typically a sign of a code smell.

Nope -- poor comments are poor, and good comments are good. There's no problem with writing good inline comments to explain an un-obvious function or tricky algorithm.