It’s worth mentioning that some people hate syntax highlighting, and claim that it is distracting or gives them a headache.  My guess is that most of these people have never had the chance to work with a subtle-yet-attractive color scheme.  It’s a pretty well-accepted fact syntax highlighting is useful for catching typos and various bugs.  It takes a bit of training to notice when something highlights in an unexpected way, or doesn’t highlight when it should, but an eye for it can really improve your code quality.

Philosophy

• Nothing should be bold unless it’s very important and should stand out above all other things. Functions/classes are good for this.  (I’m actually using a font/size now that does not support bold.)
• Colors should be easy on eyes to stare at for many hours.  The background should be extremely comfortable for your eyes, so not white, and probably not even black.
• Todos should stand out just a little (underline looks nice).
• Inline comments should stand out less than anything else.
• Code “commented out” should be nearly invisible.
• But real in-code documentation should have strong emphasis and beauty.
• Everything should be differentiated, including identifiers, keywords, 3-4 types of comments, strings, types, constants, conditionals, control structures, and more.
• Strings should be a nice color since much documentation should exist in source code as strings (think “”" comments in python or /** in java).
• Normal text should be colored either black or white so it is obvious if something is not recognized syntax.
• No two used colors should be highly similar.  Beauty is secondary to contrast.
• Each language will have some special syntaxes that need specific attention.  E.g., py, pl, sh, html, vim, rst, moin, mail, etc.  It’s helpful to have a variety of file types hanging around and fire up your editor on each of them for the scheme you’re developing/modifying.
• The scheme should look nearly identical whether being used in an xterm or in a GUI.  E.g., looks the same in vim as gvim.
• Really needs to support 256-colors.  There are just too many different highlights to try and cover in 16 colors.

I’ve described the different types of comments in this related post.

Have a look at the repository of color schemes for vim.  There is also a nice screencapture of the repository.

Download my pythoncomments patch to enable python.vim syntax recognizer (for v2.6.3, maybe already part of your Vim installation) to make use of the various features of this article.  The patch is not necessary, but helps with some comment highlighting.

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.