Skip to content

Naming Code

January 28, 2014

There are a bunch of programming books that have dramatically effected how I write, organize, and maintain code, whether it’s an HTML template, a Javascript file, XML, Freemarker, PHP…anything I’ve been asked to use or fiddled with on my own.

I rarely think of myself as a programmer or an engineer, because most of the day-to-day activities in user interface “programming” largely consists of integrating the efforts of many different people and disciplines: graphic design, back-end applications, templates, information architecture, accessibility, internationalization, optimization, editorial guidelines…making a user interface involves a lot of cross-discipline work and ‘soft’ skills. This is generally how I’ve positioned myself over the years…as a generalist that specializes in communicating between the many different groups that come to the table to build a site, and integrating that in a way that benefits the client.

But you didn’t come here to read my LinkedIn mission statement. Let’s get back to it.

Both the Pragmatic Programmer and Code Complete are must-reads, although I’ll admit that Code Complete is so massive it may take a few tries to get all the way through (I read the first edition and that’s what I’ve linked to, but there’s a second edition out now). Seriously, you can kill small animals with this thing…it’s ideal for home defense.

One of the better books I’ve read, and one I keep coming back to over and over, is The Elements of Java Style, a collaborative effort by a group of coders that worked at Rogue Wave Software. Several permutations of those authors, in conjunction with a few new faces, have released similar versions for both C++ and C#. All the books are issued by Cambridge University Press, and all are awesome.

I don’t know much about Java, let me say that right off the bat. And most of the latter half of the book is advanced topics that only make sense for folks programming in Java. But the first half discusses code formatting, documentation style, and naming conventions that I’ve taken to heart over the years, and anyone who’s seen my CSS or Javascript will recognize this book’s influence on how I name things.

Which is, finally, what I want to discuss.

Naming conventions can truly make or break projects or teams. As someone who’s suffered through a half-dozen ASP Classic projects, all written in Hungarian Notation, VB style, I can tell you that not standardizing on something that makes sense for the whole organization can be disastrous. I’m going to wait for all the Hungarian enthusiasts to stop throwing strFruit at the monitor before we continue.

While I’m not going to copy verbatim what’s said in The Elements of Java Style, I’m going to share my interpretation of it here.

Classes/Superclasses/Modules: written in UpperCamelCase.

Methods/Functions/Subroutines: written in regularCamelCase.

Constants: All UPPERCASE.

Hashes/Dictionaries/Arrays/Collections: regularCamelCase.

All other variable types: regularCamelCase.

There’s two sets of extra distinctions. The first is that classes are nouns and methods are verbs. The second is that arrays are plural and variables that can only contain a single value (strings, numbers, boolean) are singular.

So, a really simple (useless except for demonstration purposes, actually) Javascript object would look like this:

AcmeWidget = ( function() {
	var acmeHammer = '',
	    acmeNails = [],
	    COYOTE = "Wily";

	dieDieDie = function() {
	    //TODO: obviously doomed-to-fail
	    //nefariously nefarious plan
	    //written entirely in regular expressions
	};
}());

The Javascript notation and formatting isn’t really relevant here. It’s how the names of the parts read. Making classes nouns and methods verbs make them easily distinguishable, even without the added capital letter in the front. You immediately know that a variable contains a collection because it’s pluralized. Constants are rarely an issue for me because I rarely use languages that have them, but once you’ve established the convention in a language that doesn’t support them, people can tell which variables they shouldn’t mess with.

The beauty of these conventions is that they don’t make any assumptions about the problem you’re trying to solve. You can use them to build a Javascript carousel or a heart monitor. The conventions make no assumptions about your problem domain, making them endlessly re-usable.

The best thing for me? A simple restriction to make them usable with CSS classes and id’s (no punctuation, can’t start with a number) makes the scheme easily extendable to CSS. Combine that with the fact that these conventions work in most server languages, and you only need to standardize on a single naming convention.

The Elements of Java Style goes on to make a few more suggestions, like standardizing on the names of throwaway variables (i, j, k, etc) and standard prefixes for methods that do the same thing (get/set/is). Most of these come from the Sun Java Style Guide now maintained by Oracle, and are part of the style guides for many other languages. Incorporating them shouldn’t be much of a problem, as they’ve entered programming folklore for the most part, anyway.

I’d suggest trying them for your next project, whether you’re writing in a procedural or OO language, writing CSS or Javascript. It does take a bit of time to get used to, but I love the flexibility and clarity I get from a few easily-remembered rules. They make reading the code I write a breeze when I come back to it weeks or months later.

Advertisements
No comments yet

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: