javascript

Chapter 20: Best Practices
Another part of readability is comments. In most programming languages, it ’ s an accepted practice to
comment each method. Due to JavaScript ’ s ability to create functions at any point in the code, this is
often overlooked. It is perhaps even more important to document each function in JavaScript because of
this. Generally speaking, the places that should be commented in your code are as follows:
❑
❑
❑
❑
Functions and methods — Each function or method should include a comment that describes
its purpose and possibly the algorithm being used to accomplish the task. It ’ s also important to
state assumptions that are being made, what the arguments represent, and whether or not the
function returns a value (since this is not discernible from a function definition).
Large sections of code — Multiple lines of code that are all used to accomplish a single task
should be preceded with a comment describing the task.
Complex algorithms — If you ’ re using a unique approach to solve a problem, explain how you
are doing it as a comment. This will not only help others who are looking at your code, but will
also help you the next time you look at it.
Hacks — Because of browser differences, JavaScript code typically contains some hacks. Don ’ t
assume that someone else who is looking at the code will understand the browser issue that
such a hack is working around. If you need to do something differently because one of the
browsers can ’ t use the normal way, put that in a comment. It reduces the likelihood that
someone will come along, see your hack, and “ fix ” it, inadvertently introducing the bug that
you had already worked around.
Indentation and comments create more readable code that is easier to maintain in the future.
Variable and Function Naming
The proper naming of variables and functions in code is vital to making it understandable and
maintainable. Since many JavaScript developers began as hobbyists, there ’ s a tendency to use
nonsensical names such as “ foo ” and “ bar ” for variables and names such as “ doSomething ” for
functions. A professional JavaScript developer must overcome these old habits to create maintainable
code. General rules for naming are as follows:
❑
❑
❑
Variable names should be nouns such as car or person .
Function names should begin with a verb such as getName() . Functions that return Boolean
values typically begin with is , as in isEnabled() .
Use logical names for both variables and functions, without worrying about the length. Length
can be mitigated through post - processing and compression (discussed later).
It ’ s imperative to avoid useless variable names that don ’ t indicate the type of data they contain. With
proper naming, code reads like a narrative of what is happening, making it easier to understand.
Variable Type Transparency
Since variables are loosely typed in JavaScript, it is easy to lose track of the type of data that a variable
should contain. Proper naming mitigates this to some point, but it may not be enough in all cases. There
are three ways to indicate the data type of a variable.
The first way is through initialization. When a variable is defined, it should be initialized to a value that
indicates how it will be used in the future. For example, a variable that will hold a Boolean should be
637