expand comments section

I did some work on expanding the comments guidelines.

Any feedback is appreciated.
I think this is redundant with the section on imports (style/imports.html) -- is there something beyond those general guidelines that particularly applies to code snippets in doc comments?