By Nicholas Zakas CHAPTER 2Without the comment, you might wonder why 138.5% is a significant
number. With the comment, you know two important pieces of informa-
tion. First, this file requires the YUI Fonts CSS foundation to work proper-
ly. Second, 138.5% is equal to 18px based on that requirement. What could
easily have been a source of confusion is now a source of information and
understanding.
How do you know if code needs a comment? Think of comments as
Post-it notes in your code. Anytime you’re afraid you may forget what the
code is doing or how it’s doing it, add a comment. Anytime you come across
something that might trip up another developer, such as a browser-specific
hack, leave a comment. If you’re implementing a specific algorithm, leave a
comment. Leave a comment whenever you feel like you’d be missing some
important information if you went away for six months and then needed
to work on the code again.
Good developers make judicious use of comments and don’t expect
the code to speak for itself. You shouldn’t need to read through all of the
code just to make sense of what’s going on. Comments short-circuit that
need by providing narrative that more succinctly describes what the code
actually does. And that is incredibly valuable for the long-term hygiene of
your code.
MaKe eRRoRS obviouS
One of the most important reasons to have a coherent style guide is to help
make errors more obvious. Style guides do this by familiarizing developers
with certain patterns. Once you’re acclimated, unfamiliar patterns jump
out of the code when you look at it. Such patterns aren’t always errors, but
they definitely require a closer look to make sure that nothing is amiss.
For example, consider the JavaScript switch statement. It’s a very com-
mon error to mistakenly allow one case to fall through into another, such
as this: