Naming in software development is in just about everything we touch: variables, arguments, functions, the name of files and folders. In most cases developers don’t pay the naming of things the respect it should be given. The second chapter of Clean Code is all about this.

A (newish) pet hate I have with anyone who does examples (this includes me in previous postings / presentations) is the use of foo and bar! WTF do they mean! Give some context if you’re an evangelist for a product / technology please for the love of clean code and the long life of your product use meaningful names. This also goes for fellow bloggers, people will see what you’ve done and then think it’s ok to do it. Especially if you’re an evangelist, people will think they work for X Company and they do it so it must be “Best Practice” (The concept of Best Practice is another topic / pet hate of mine)

If the value that the variable or argument will hold is a date of birth call it dateOfBirth, or DOB or usersDOB not FOO or birth or d. Give it a name that means something. Your Christian name means something; at least it did to you parents when they gave it to you. I’d guess in 99% of cases they spent a long time deciding what to call you. Give the same respect to your variables, arguments and functions; they will last as long as you have if not longer in some cases. Think about the Year 2000 problem, the people who wrote those apps didn’t think they would last that long. It can happen, although in the Web Application word most apps get rewritten every 5-10 years so less chance of them lasting.

A well-named variable makes it easier when you come back to the code in the future; it also removes the need for comments (This is another topic in a later post). The name of variables, arguments and functions should try and tell a story about the process. This makes it easier to follow, when you have to come back to it to make changes. When I say a story it should be one that fits the domain of the problem or solution, not one of Alice in Wonderland (Although I have been told of someone who did this for an app and it made sense, although was a nightmare to debug).

Naming of anything is one of the hardest things a developer can do, (http://www.itworld.com/slideshow/124383/arg-9-hardest-things-programmers-have-do-378834#slide10) if you put the effort in it pays a lot of dividends back in the future. I use http://dictionary.reference.com & http://www.visualthesaurus.com to help me come up with the right name for what I’m working on, I also try and keep in mind the following points which are details in chapter 2 of Clean Code.

  • Use intention-revealing names
  • Avoid disinformation
  • Make meaningful distinctions
  • Use pronounceable names
  • Use searchable names
  • Avoid encodings
  • Avoid mental mappings
  • Don’t be cute
  • Pick one word per concept
  • Don’t pun
  • Use solution domain names
  • Use problem domain names
  • Add meaningful context
  • Don’t add gratuitous context

I toyed with the idea of giving my own spin on each of these areas, but to be honest I can’t do any better than the book so please go grab Clean Code today

As I’ve already said you will read more code then you write, so put a little thought in to what you’re doing and come up with the best you can do. If you come back to your code and think of a better name then change it remember “The Boy Scout Rule”.

To this end, please stop giving anything you work on crap names! Give your code and your fellow developers some respect and use meaningful names.

 

One Response to Software Craftsmanship – for CFML Developers Part Five – Meaningful Names

  1. Aaron Martone says:

    True enough, Kev.

    As far as method goes (where applicable), I love the verb+noun format. getDateOfBirth(), processConfigXML() convertStructToArray() (Notice how we don’t use the number ’2′ for ‘to’… I HATE that)

    I am a HUGE stickler for my naming conventions. Consistency breeds familiarity, and familiarity breeds easier comprehension.

    The ONLY time I use non-sensical variable names is in my loops. I don’t even like using local.i for my loops. I use local.index, and in the event I need nested indexes, I’ll rename both to use descriptive indexes, ie: local.superIndex, local.subIndex, local.subSubIndex, etc.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>