Many Types of Code Comments

It’s amazing how many different purposes there are for code comments.  Most comments are treated the same by compilers/interpreters — ignored.  But humans have their own semantics based on some established conventions.  And “meta-processors” also do a lot with these; e.g., generating documentation, running tests, executing debug statements, locating tickets, assigning to variables, syntax highlighting and checking, compiler diagnostics control, editor folding, hidden full-blown languages, and probably even more.  But the point of this post is to simply enumerate the common comment types.  I’m working on some syntax highlighting for Vim to make more semantic sense of these, particularly for Python code.

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.

Tags: checklist, color, ocd, vim