Hi, my name is ___

Photo of 4 iPhones saying helloby Daniel Romero on Unsplash

One of our most frequent tasks as programmers is assigning names.  It’s hard to go an hour without coming up with a name for a class, a method, or a variable.  But naming things is hard for at least two reasons:

  1. The exact purpose of an item might be not be clear until you’ve written its body or used it in context.  I often use a clearly inappropriate placeholder that will force me to replace it once I have a good name.
  2. Picking appropriate words is tough.  It can be hard to spend time selecting the right word when you’re focused on writing logic, but often the work of naming will help clarify that logic’s organization.

Here are some suggestions for naming rules, born from recent experiences.

Rule: reflect the usage and context

A name is the first and most important way a reader will determine what something does, and whether it’s the appropriate something to use.

If a class has a very specific context in which it’s useful, reflect that context in the name or its containing package.  On the other hand, think forward to future uses of a class, and don’t unnecessarily restrict it to Foos by calling it FooEngine when it might also be useful for Bars.

Rule: influence the named object’s scope

Names can act as a valuable indicator that the scope of a class or method has grown too big.  If a good name doesn’t seem to comprise the full functionality any more, or conversely the functionality is suggesting a name that involves too many steps, then consider factoring out some of that functionality.

A class named SearchEngine that’s also used to retrieve user configured paths needs to be refactored into at least two classes.  A method named ValidateUpdateNotify (or more problematically, Process) should actually be three separate methods.

Rule: name length is inversely proportional to usage frequency

The more frequently a name will be used, the shorter it can and should be.  The length and obscurity of names impacts how other developers use the named objects.  In the following comparison, split is idiomatic, familiar, easy to read, and easy to remember; componentsSeparatedByString is much less so:

# JavaScript, Ruby, Python
'a b c'.split(' ')

# Objective C
[@"a b c" componentsSeparatedByString:@" "]

Apple’s very long method names such as tableView:accessoryButtonTappedForRowWithIndexPath: have a clear benefit of being self-documenting and are appropriate for less frequently used API classes.  But for the more common classes and methods in a language, API, or project, they add an unnecessary burden to the developer.

Rule: unique names are searchable names

If you ever need to refactor a widely used method or search the git commit history for the introduction of a variable, you’ll be grateful if the name is unique.  For example, name a class PurchaseOrder or JobOrder rather than Order, which will easily be confused with sorting or other meanings for the word.

Rule: alphanumeric names are Googleable names

If your name is as popular as "C#", search engines will return good results; otherwise, avoid special symbols in public names since they tend to be chomped from queries.  This rule becomes doubly important if the name is not otherwise unique. For example, the JavaScript library jQueryMX (now rechristened Can.js) borrowed the "$" prefix from jQuery, and named its most important classes $.Model and $.Controller.  Try searching Google or jQuery’s own forums for "$.Model", and the results are next to useless.  Obstructing your users’ most important tools for gathering and sharing information about your framework is a sure way to consign it to oblivion.

Rule: rename when necessary

In many cases, it’s hard to get a name right the first time, particularly when requirements or architecture change.  As a project evolves, make sure to keep the above rules in mind and rename your classes and methods when their roles change.  Don’t let a name rot into inaccuracy.

Read more

The subject of naming has been a popular one over the years.  Here are some worthwhile posts:

Deploying Websites with Git

Graphic of Git Logo

Deploying your webapp is an important part of the web development equation – your client’s site isn’t going to attract a lot of attention sitting in your local dev directory. Deployment concerns tend to fall to the bottom of the priority list, though, and the end result tends to be kludgy, hastily thrown-together deployment scripts; and because they are so kludgy and, often, time consuming, when time crunches threaten, a developer may resort to making changes directly on the remote server that need to be (but sometimes never are) backported to the code living in your version control.

Wouldn’t it be better if you could deploy your newest code with a single command, using the same tool you use for version control? One git push, and your site is serving your newest commits. No more kludgy, multi-part scripts, no more threat of overwriting critical fixes with the next deploy.

Let’s make that happen.

(more…)

Gate External Links in Kids’ Apps

Photo of wall and gate by Henning Kesselhut on Unsplash

Release after release, Apple raises the bar on its requirements for inclusion in its app store.  Sometimes these are welcome technical changes, like explicit user permission to access contacts.  Other times they feel more like hurdles for app developers and users to jump – or in this case, the appropriate metaphor is stepping through a flimsy backyard gate.

iOS 7 introduced a new requirement for kids apps:

24.3 Apps primarily intended for use by kids under 13 must get parental permission or use a parental gate before allowing the user to link out of the app or engage in commerce

This requirement was probably inspired by the Children’s Online Privacy Protection Act (COPPA), which establishes rules related to collecting personal data from children.  Apple applies the requirement to interface elements like iTunes app store links and social sharing buttons.  However, the requirement is remarkably non-specific as to what constitutes a sufficiently sturdy parental gate.

(more…)

error_log() On Strike A.K.A. Debugging PHP Applications in Mavericks

Image of ants debugging a fly. Photo by Juan Pablo Mascanfroni on Unsplash

Ever seen this in your production php_error.log?

[16-Dec-2013 10:50:44 America/Denver] Hello there
[16-Dec-2013 10:50:44 America/Denver] ...starting loop
[16-Dec-2013 10:50:44 America/Denver] stepping through 0
[16-Dec-2013 10:50:44 America/Denver] stepping through 1
[16-Dec-2013 10:50:44 America/Denver] stepping through 2
[16-Dec-2013 10:50:44 America/Denver] stepping through 3
[16-Dec-2013 10:50:44 America/Denver] stepping through 4
[16-Dec-2013 10:50:44 America/Denver] stepping through 5
[16-Dec-2013 10:50:44 America/Denver] ...done
[16-Dec-2013 10:50:44 America/Denver] How in the world did we get here?

There’s one thing you can tell about the developer who wrote it – they don’t have a debugger up and running.  Or maybe they do, it’s just too big of a hassle to fire it up and get it attached.  And I am plenty guilty of this myself, having written my share of debugatory error_log statements over the years.  Sometimes it’s just easier to add a trace, refresh, and tail the error_log.

Debuggers, at least those available for macs, are finicky beasts.  They’re often difficult to setup, they’re a bit too assertive when you’re not actively debugging, and they don’t always work reliably.  Compared with a debugger, error_log() is always there for you, seldom complains, and rarely sticks it’s nose in where it doesn’t belong.  Why can’t a debugger be this way?  I need to admit that nothing about what I’m going to say is ground breaking.  There isn’t a new debugger out there that works better than anything before.  There isn’t anything new in Mavericks that makes debugging easier.  It’s just the fact that after 5 years of typing error_log("Here I am") over and over as my debugging solution, I’ve finally found a debugging setup that works without a lot of fuss.  And that seems to be the key for me…in order to use it, it needs to come without a lot of fuss.

First, let’s talk about the elephant in the room…

(more…)

Meteor: Introduction and Example app

Photo of meteor by Lamna The Shark on Unsplash

I’ve just discovered Meteor and I’m currently in the honeymoon phase of this relationship. I realize that it’s still early in development but it’s one of the first truly inspiring full-stack web development platforms I’ve seen in a long time. Built on node.js, it consists of a JavaScript server (in a node.js container) and JavaScript client. The dynamic interaction between the client and server allows for a very simple, seamless way to create surprisingly complex web applications. In short, any changes to the back-end data automatically update front-end templates that use that data.

(more…)