Different Types of Comments

Of course the code highlighting plugin this blog uses isn’t able to make much sense of these, but Vim can take it further with a little tweaking.

# look out for...
#print 'disabled
##print 'disabled'
for x in xs:  # iterate over xs
### King comment.
###print x
"""Multi-line chunk of commented-out code.  Sometimes only first sentence is significant."""
'''multi-line chunk of docstring'''
"string"
'string'
# TODO: add locking to...
######################################################################
#---------------------------------------------------------------------
# @param foo The metavar that never dies

I’ll break these down by line number.

1. is just a traditional comment that exists because something out of the ordinary is happening around the code.
2. a disabled line of code
3. another disabled line that is easier for a highlighter to treat.
4. an end-of-line comment; the most subtle form.
5. is a descriptive comment marking the purpose of a section of code.
6. a statement that only executes when in “debug mode”.  Perl’s “smart comments” are the only facility I’m aware of that uses this, but I think they’re pretty clever.
7. a formal piece of documentation, usually spanning multiple lines.
8. a simple way to comment out a large chunk of code.
9. just a string
10. same as 7; probably should not be differentiated, but some people prefer to the “dirk” version whenever possible.
11. a codetag (a controversial convention many use to refer to items that should (or do) have tracker tickets associated; described in PEP 350).
12. a break in major section of the file.
13. a minor section break.
14. a “javadoc”-style piece of documentational markup.  Also available with Epydoc.

View From Vim

For a more visual example, here’s a screenshot showing the best I can make Vim do today. Featuring the Adobe color theme, tokenized by python.vim.

It is certainly within reach to make Vim, emacs, and probably many other editors make use of these semantics in their syntax highlighting.  That color scheme (hacked up for this display) is not (yet) perfect, but it does the job of showing most of the differentiation. If there are so many purposes for the different comments, shouldn’t your editor make those differences obvious?

I’ll offer more details about getting this working, and the value of highly differentiated syntax, and what makes a good color scheme, in a near-future post.