color-coding javascript for a beginners book

October 9, 2006 1:51 PM

I'm writing a book on programming for beginners, and I have a question about color-coding.

The book is about programming Javascript within an Adobe application. It's intended for designers who want to learn a little about programming in a very specific environment -- not for advanced scripters or people wanting general knowledge about JS. I'm really excited, because my publisher has agreed to print the book in color, which is rare for a book on programming. So I want to make the most of this, and use color-coding to help explain the code.

I can pretty much set up the editor I'm using to color things any way I want. (I'll be taking screenshots of the code in the editor to use as examples in the book.)

When I program, my preference is to use many colors to indicate all sorts of nuances of the language. But I fear that too many colors will be overwhelming for beginners. I want colors to help illuminate -- not confuse.

Here's my thinking right now: three colors.

1. darkish red for language elements. This includes keywords, DOM words, operator symbols and built-in functions/methods.

2. black for anything the user (programmer) can make up: variable/function/object identifiers and data.

So in the statement, counter = 12;, "counter" and "12" would be black and "=" and ";" would be dark red.

I'm doing this, because when I teach intro programming classes, the greatest point of confusion seems to be what you're allowed to name and what you're not allowed to name. No matter how well I explain variables and the like, when I type...

userName = "Fred";

... beginners get confused and think that they MUST type "userName" if they're doing something similar. Then, when they see that someone else has typed...

uName = "Fred";

... they get really confused.

3. gray for comments.

Also, there will be line-numbers in the screenshot, and I'm trying to decide how best to format them. I want to be able to refer to them in the code, but I don't want them to be distracting -- to get in the way of the code.

I know there's a big difference between keywords and built-in identifiers of DOM elements, but under my system, they'd both by dark red. What is your feeling about this?

Remember, the book is intended for people who want to use JS to program a specific application, not for people who want to learn JS as a general-purpose language. I do want people to be able to go on to other JS systems if they want to -- and not be confused by my book when, say, they find out that web browsers have a different DOM from Adobe applications -- but that's not the main focus of the book. So that has to take second stage.

Most of my readers will fall asleep if I go into JS as a general-purpose language. They don't care about programming web browsers or Flash. For the few who do, I plan to include sidebars, but it seems to me like this is just confusing info -- given the intended audience -- if I include it in the book's main examples.

Do you agree or disagree with this philosophy? Why? Do you have any suggestions for color coding? Do you know of any good examples I could look at?

posted by grumblebee to writing & language (36 comments total)

There is often another color used for constants, like "Fred" or 12, to make it clearer where the original value of the variable came from.
posted by smackfu at 2:00 PM on October 9, 2006

smackfu, that's exactly the sort of thing I'm mulling over. Another color for constants will be -- well -- another color. Is that more confusing or more helpful?
posted by grumblebee at 2:08 PM on October 9, 2006

I really, really don't like the idea of language keywords being the same color as library identifiers. The thought fills me with revulsion for some reason. I don't think it is necessary to put symbols in a special color.

Personally, I really like the way Emacs python-mode works.
posted by grouse at 2:11 PM on October 9, 2006

Many IDEs automatically colour code your code. Is there a specific IDE that readers of your book are most likely to be working in or an IDE you plan to recommend? I'd want to the book's colour coding to match the IDE's default.
posted by jacquilynne at 2:13 PM on October 9, 2006

Jacquilynne, I'd definitely match the IDE if there was one. But readers will be programming in a plain text editor. (The book is about After Effects, and that's all AE offers.) Of course, they COULD download a 3rd-party editor, and I'll definitely point them towards resources. But each editor is going to color-code things in a different way.

I will include plenty of screenshots of the "vanilla" editor that comes with After Effects, and I will be clear to readers that this editor DOESN'T color code.

But I'd still like to use color (and my publisher would like me to use color) as a teaching tool.
posted by grumblebee at 2:17 PM on October 9, 2006

I'm used to language keywords being one colour, strings being another colour, and everything else being neutral, probably just black.

I think anything else is going to be too fussy. This kind of thing:

>So in the statement, counter = 12;, "counter" and "12" would be black and "=" and ";" would be dark red.

seems like overkill to me.

Reverse-engineering my opinion from a position of "that's just the way BBEdit does it" ... language keywords like "for" and "while" are "magic". They're part of the language and do special things when you invoke them. So they're different.

Then, strings need to be coloured so that you know you've closed the properly. If your whole page is red from line 23 onward, then you've messed up the quotes on line 23.

Everything else is just typing.
posted by AmbroseChapel at 2:25 PM on October 9, 2006

Another thing to worry about is color-blindness. There are several variants (some more common than others), but you might want to pick colors such that any pair of them are still distinguishable by the most common forms of colorblindness. Otherwise, to some of your readers, they'll wonder why two classes of text that don't seem to be related have the same color. (BTW, I don't see, off the top of my head, anything wrong with the proposals so far but I'm not in any way an expert.)

Also, seconding the comment by AmbroseChapel about strings being some color. Colors for strings are a lot easier to see in many fonts than quote marks.
posted by R343L at 2:43 PM on October 9, 2006 [1 favorite]

Visual Studio is the most widely used IDE, and you can download it from MSDN. It would make sense if you just used their colour conventions.
posted by randomstriker at 2:47 PM on October 9, 2006

you might want to pick colors such that any pair of them are still distinguishable by the most common forms of colorblindness.

Good point! Any good resources on this?

Re: strings. I agree that it's VERY helpful to have a color for strings when you're programming, so that you remember to close them. But please note that I'm NOT using color to help the reader avoid syntax errors (I'd like to, but I can't, since the editor they'll be using doesn't include color-coding). I'm using color to help teach programming concepts.

I don't want to use it to teach ALL programming concepts. I'm trying to choose one or two KEY concepts that can be clearly and easily shown with color.
posted by grumblebee at 2:49 PM on October 9, 2006

Visual Studio is the most widely used IDE, and you can download it from MSDN. It would make sense if you just used their colour conventions.

I think it would help if I clarified a bit about my readers. These people are DESIGNERS and ANIMATORS, working in an app that -- until recently -- didn't include scripting. Now it does. The purpose of the scripting is to help them create animation effects that are hard to do using conventional animation techniques.

Most of them are scared to death of scripting, and this is going to be a hold-their-hand book.

They are not going to write long programs, and they are going to flinch at downloading a major programming tool.

I will admit that this desire that many designers have -- to not really learn a language but to just dabble in it -- is understandable but ultimately unworkable. So I DO plan to really teach the language, but this will be in a Part II. Part I is just about getting their feet wet, clearing away the fear, and showing them how to do some cool things.

Imagine for a minute that you were teaching an intro programming class for designers, and that you were writing code on a whiteboard -- not in an editor. You have a bunch of markers, all different colors. How many of them would you use and for what?
posted by grumblebee at 2:54 PM on October 9, 2006

Grumblebee, I think you're on the right track. For a non-programmer, I see no reason to distinguish between keywords and built-in functions. There's no difference, it's all part of the "language" as far as the reader will be concerned. Like you said, something they have to type verbatim vs. something they can make up.

I think it's immensely helpful to highlight particular lines of code in a code example if you're trying to demonstrate a specific concept. Or if you have incrementally built-up samples, highlight the lines that have been added/changed from page to page. Raymond Chen does this nicely in his coding articles. For example. That's huge since a lot of code is boilerplate.

You can also use other typography besides color. Bold keywords, for example. That keeps your color palette simple.
posted by Khalad at 3:17 PM on October 9, 2006

I agree with khalad, although I would flip around the colors you are using.
* Blue (or red or green) would be "things the programmer can choose" (variables, function names, etc).
* Black would be "things that are defined by the program."
* Grey would still be comments.
Anything much more complicated than that starts to get confusing.
posted by muddgirl at 3:30 PM on October 9, 2006

muddgirl, how come you'd swap the colors? Fine if it's just a gut feeling, but I'm hoping you can put it into words.
posted by grumblebee at 4:13 PM on October 9, 2006

I agree that you need another colour for comments. Should have said.

>I agree that it's VERY helpful to have a color for strings when you're programming [...] But please note that I'm NOT using color to help the reader avoid syntax errors [...] I'm using color to help teach programming concepts.

I don't think that negates the idea though. A string is a programming constant. I think I'd like to expand the idea so that string and number constants are a particular colour.

I mean, break it down. What does a programming language consist of?

1. keywords and built-in functions (I want to lump them together)
2. variables you create like scrollingSpeed or screenWidth or whatever
3. constant values like strings and numbers
4. comments
5. operators

Have I missed anything? A colon at the end of a line ... does that come under "punctuation" or is it really the "my statement ends here" operator? What's a DOM address, is it another thing, or is it just a function that returns the object at that address?

The argument can be essentially reduced to "which of those things needs its own colour"?

I'm arguing for a four-colour system:

• keywords/functions,
• constants,
• comments,
• everything else.

You'd rather have five, one for each of the above?

There's not a huge difference I suppose. On the practical level however, colouring a semicolon differently to everything around it calls for a pretty strong colour contrast, which could make the thing hard to read. I don't want hot pink or lime green semicolons, I'd go crazy.
posted by AmbroseChapel at 4:16 PM on October 9, 2006

"A string is a programming constant."

I meant "A string is a programming concept."
posted by AmbroseChapel at 4:18 PM on October 9, 2006

Is the quality of the printing going to up to this? At code-example point sizes the registration will have to be artbook-tight to pull it off.
posted by bonaldi at 4:58 PM on October 9, 2006

Don't books have designers and publishers for this sort of thing?

I'd be surprised if there wasn't some sort of standard out there for exactly this problem. Perhaps your publisher has a style manual?
posted by oxford blue at 4:58 PM on October 9, 2006

Because to me, black is the color of text. From my completely subjective perspective, text written in black is un-malleable. Text that's different is text that can to be played with.

I can see a couple reasons to choose red over black for built-in functions: the author will want to highlight the stuff that's actually important. Red is a natural choice over black because it says LOOKEE HERE.

Actually, if I were to write a book with coding examples, I wouldn't use any color at all, really. I'd use black for built-in things and a lighter shade of grey for user-defined variables and comments. If I were writing this on a white board, I'd probably use black and blue, like my example above.
posted by muddgirl at 5:00 PM on October 9, 2006

Don't books have designers and publishers for this sort of thing?

I'd be surprised if there wasn't some sort of standard out there for exactly this problem. Perhaps your publisher has a style manual?

This company doesn't generally publish coding books. It was a huge decision for them to post this one. Coding, for the AE community, is really interesting. About 90% of AE users are interested in JS but also really scared of it.

I pitched a JS/AE book to my publisher a couple of years ago, and he said it wouldn't sell. Then I invited him to a conference, where I was speaking about JS to AE users, so that he could see the crowd. About 400 people showed up (many of the other conference sessions housed about 30 people). They were almost all people who'd never written a line of code. But they were really longing to find someone who could ease them into the subject.

I'm writing the book with a co-writer, who is really good at more complex stuff, and by then end of the book (he's writing the second half), we'll be covering 3D, movement-based animation, using Trig.

But we have to start really really simple.
posted by grumblebee at 5:23 PM on October 9, 2006

What does a programming language consist of?

1. keywords and built-in functions (I want to lump them together)
2. variables you create like scrollingSpeed or screenWidth or whatever
3. constant values like strings and numbers
4. comments
5. operators

6. Objects (and their properties and methods).

I agree that languages contain all these elements. I'm still mulling over how important it is -- in this specific book -- to continually remind the reader of this via color.
posted by grumblebee at 5:27 PM on October 9, 2006

Here's what I'm thinking about.


posted by grumblebee at 5:39 PM on October 9, 2006 [2 favorites]

See, that example really solidifies it for me. I keep looking at the black, not at the red. But maybe that's just me. As long as they're differentiated, it probably doesn't matter that much.
posted by muddgirl at 5:44 PM on October 9, 2006

I think you're right, muddgirl. The black draws focus. But I'm not sure that's a bad thing.
posted by grumblebee at 5:46 PM on October 9, 2006

Here's another example, this time with data constants a different color:


posted by grumblebee at 5:56 PM on October 9, 2006

The first is alright, but you need to tweak the colours. The second is pretty bad.
posted by oxford blue at 6:04 PM on October 9, 2006

How should I tweak the colors, oxford blue?
posted by grumblebee at 6:27 PM on October 9, 2006

When you pick your colors, try to avoid colors that are indistinguishable to those with deuteranopia. If you view this page through Vischeck you can see how it looks.
posted by plinth at 6:44 PM on October 9, 2006

With a warm hand, and fairly slowly. Ahem.

I would have the red and black less contrasty so it's less distracting. It's hard to read the read, because the eye keeps getting attacted to the black.

I'd try Black, Blue (instead of red), with a light (i.e. not neon) yellow highlighting.

Is it possible to have a little more white space between the line numbers and the code?
posted by oxford blue at 6:46 PM on October 9, 2006

Looks like my images is okay, plinth, but thanks -- great linke.
posted by grumblebee at 6:48 PM on October 9, 2006

Is it possible to have a little more white space between the line numbers and the code?

I agree it's a problem. I'm working on it. (I know I can create space in Photoshop, but I'm trying to come up with a less labor-intensive solution right in the editor.)
posted by grumblebee at 6:50 PM on October 9, 2006

I am not a designer or even a really good programmer, but I've read probably about 10 different programming books in my day and I enjoy editing with really colorful schemes. That said, I will point out that one of my favorite programming books from college uses this scheme:

line numbers and comments - blue
everything else - black

The book is: Computer Systems: A Programmer's Perspective (Bryant and O'Hallaron).

Code Complete 2, probably the best programming book I've ever picked up is black on a gray background. Finally, Dive into Python (which I think has been alluded to, but not referenced, uses 3 colors).

I think four is too many for a book, I think red is distracting, and I think you should Keep It Simple. However, I'm also not your audience.
posted by onalark at 6:53 PM on October 9, 2006

I'm starting to get won over to the "red is distracting" camp.
posted by grumblebee at 6:56 PM on October 9, 2006

I agree that black = unchanging text, and would look better than the red.

Red looks like "danger! don't mess this up", which is too strong a statement for code that you can simply copy character for character.

If I were the target audience, I'd be much more interested in what I can do to customize the code, so you might want to highlight just the variables so they stand out. Perhaps with blue?

In summary:

code - black
variables - blue (or green as in "green light, OK, go")
comments & line numbers - gray

Let us know when the book comes out!
posted by QueSeraSera at 10:02 PM on October 9, 2006

You have to be careful with utter neophytes -- they're going to wonder how to get the text to be the right color when they type it in. They're going to assume that if it's not the right color it won't work, or if it doesn't work that it's because they didn't figure out the colors (rather than because they made a subtle typo, which is usually the case). You can explain it at the beginning, but remember, people won't read your book even though they bought it, they will instead read random sections of it that seem to them to relate to their problem, in random order.

Use Courier or whatever font AE uses in its script windows. Make it look exactly like it will look on their screen when they type it in. If AE doesn't use any typographical embellishments, then don't add any to your book.

You're getting answers here from people who already know how to program, but these are not your audience.
posted by kindall at 10:49 PM on October 9, 2006

I love the idea of colour coding, but I'd prefer it if it was used to highlight the new idea in the example. ie. follow the constant through, or the two "new" lines in previously used code.
posted by kjs4 at 4:14 AM on October 10, 2006

You can explain it at the beginning, but remember, people won't read your book even though they bought it, they will instead read random sections

I agree that this is a problem, but this book -- which is maybe misconceived -- is all about building concept on top of concept. I can't control the reader, but I don't see how a neophyte will get anything out of the book if they don't read it in order.

That said, we will, of course make it as clear as possible that the color-coding doesn't happen in the actual application. I plan to repeat this disclaimer several times, in prominent places.
posted by grumblebee at 7:03 AM on October 10, 2006