JavaScript Coding Standards
Today David writes in with his typical amount of detail. He responds to our recent topic of Naming standards with a focus on JavaScript that I find quite useful. Even if you don’t agree with everything here, I’m sure you can see some thought placed around David’s constraints far beyond personal preference. Each technique has a benefit.
David:
Most of my programming recently has been in Javascript, so I can’t say much about naming conventions around class hierarchies, but here are the patterns I like to use to make my code more legible:
- CamelCase, not under_score. Acronyms are treated as words since they’re used as a word: “getXmlData“. Globals begin with a capital, locals a lowercase to make scope a bit clearer.
- Function and method names are verbs, describing an action to perform: “destroy“, “insert“, “establishConnection“, etc.
- Objects and data structures (JSON-style objects or Arrays) are nouns, describing things you or your user are interested in. Arrays should be pluralized, so you can do “things.forEach(function(thing) { … });“.
- Booleans should describe a "property" of the data you’re working on: “hasATimetable“, “isExecutable“, so your control structures make sense: “if(isEnabled) { … }“, “while(waitingOnUser) { … }“, etc.
- Other base data types have far more discretion on how they’re named, but a general rule of thumb is that properties on an object-type data structure should make sense when read with the name of the object they’re a part of, while discrete variables should make sense on their own (makes sense, right?), so “sum“ is fine if it’s a property: “myIncome.sum“, but if it’s a "loose" variable in a function, it should probably be something like “incomeSum“.
I don’t believe in type prefixes at all, not even for Javascript with its loose type system. Why?
- Your variable names should be descriptive enough that the type is implied.
- Your functions/methods should be short enough that you can comprehend the function in its entirety just by looking at it (especially if you’re writing Javascript where high speed data processing performance *is not* on the table and code tweaks that negatively impact performance make no sense) — refactor it into sub-functions if you can’t understand it on its own.
- You should *always* have at least a one sentence comment describing what a particular function does. If it’s non-obvious, it should be more than that — explain "tricky" variables here. If you can understand what your program is doing based on the left-hand column of it’s docco output, you’re doing great. ( http://jashkenas.github.com/docco/ )
- Type prefixes have a habit of becoming misleading if you need to refactor your type, since you don’t want to touch all of the code that uses it (or worse, it’s part of your public API) and will only make things *worse* for new devs. Even if you’re diligent and run global find-and-replaces on your source tree, other developers tend to hate difficult to merge changes like that where many source files are touched simultaneously (and their just-now-working code stops working just before they commit to the repo).
- If you’re using a loosely-typed language like Javascript, you should be explicitly checking input types at the beginning of your function if they can affect the behavior of the program in a negative way, and type prefixes lull you into thinking the input will "always" be the type you’re expecting. (Your checking shouldn’t even be "type" checking, it should be constraints on the input, where type is just one constraint. You wouldn’t want to divide by zero, NaN, or +/-Infinity, right?) 6. Finally, the type prefixes are "ugly" (opinion) and distract high-level thinking about a problem with low-level implementation details by their constant presence. Possibly keeping you from throwing away the old structure for a better one built on different types.
Finally, the names of your source files should also have some sort of convention: they should almost always be nouns naming the different components of your architecture. If your language has a module system (like Perl, Python, Ruby, Node.js, etc) I’d highly recommend building your system architecture on it and keeping each component source tree as shallow as possible. It will greatly encourage source code re-use amongst projects by separating the components explicitly from one another, and understanding a single component can be done wholly inside its own source tree (or indicate a failure in one of its dependencies, but then you understand it in its encapsulated source tree).
It also encourages that the components/modules be as self-sufficient as makes sense. Node.js, the language I’ve been using lately, makes it very easy to create a module that can be included with a “require“ call, but also executed as a program on the command line.
So, my naming convention, based on Unix naming conventions, is:
componentName/
lib/
bin/
test/
doc/
readme
<manifest file, package.json for Node.js>
The code to use the component as a module is located in “lib“. If the component has a use-case as a standalone executable, the “bin“ directory contains the code for that. Code to check for regressions is located in “test“, and documentation goes in “doc“. A “readme“ is written from the perspective of someone completely clueless to everything but basic programming knowledge stumbled upon the component, and the manifest file contains directives for your language on how to turn it into a module and how to create the executable, as well as what other modules are needed for it to run.
I rarely need a second level of directories underneath the “lib“ directory since that usually implies separate modules, and I’ve never needed it for any of the other directories. Finally, the "primary" source file inside of “lib“ that is the entrance point on a “require“ I give a name that matches the “componentName“ of the directory involved.
These are all version controlled separately, and explicit versions are tagged at different times as the component is updated. Node.js’s "npm" installer allows you to explicitly choose which version you want to install, and the "package.json" file includes a "version" field to state which version the particular source tree represents. You can also mark the component as "private" so it’s never published online and still get the same benefits of the module system without opening your code. (But this development style makes it easier to open source individual components if the company decides to for goodwill/developing a standard/gpl compliance/whatever, without needing to open source the rest of your code and no "stop the presses" effort to detangle the code needed.)
In class-based languages like C++, C#, and Java, each class may be a "component" and I’d still recommend registering your classes into the class hierarchy ("org.companyName.whatever") even if locally, so you can get the same decoupling result of the module system described above (but perhaps not the auto-acquiring of required classes like described above). Not sure how to go about describing class versions, though.
That digressed a bit into source code organization, but I don’t think naming conventions can make sense without a definition of the organization they are placed within.
If you wish to share comments, questions or insights, drop me an Email at btaylor@sswug.org.
Cheers,
Ben
$$SWYNK$$
Featured Article(s)
How to retrieve the first n characters of a text field in MySQL
Ways to retrieve the first n characters of a text field in MySQL. Some example on how to retrieve the first n characters in MySQL.
Featured White Paper(s)
All-At-Once Operations
Written by Itzik Ben-Gan with SolidQ
SQL supports a concept called all-at-onc… (read more)
Featured Script
showallpk
Show all primary keys… (read more)