Readability and Naming Things

http://www.codesimplicity.com/post/readability-and-naming-things/

by princeverma • 15 years ago

52 28 15 years ago

Good article: things that are complex should have long names, things that are simple should have short names. Like the approach.

jacquesm4• 15 years ago

Things that have limited scope can usually get away with short names as well, even in a slightly more complicated context.

But since the punch card went out of fashion a while ago and bits are nearly free (screen width otoh is not) it doesn't hurt to name all your variables descriptively.

A global variable named 'i' is likely going to get you i trouble, then again, jQuery does most of it's magic using a single global that doesn't even have a name...

joe_the_user3• 15 years ago

"But since the punch card went out of fashion a while ago and bits are nearly free (screen width otoh is not) it doesn't hurt to name all your variables descriptively."

The bits are free but there's still a mental cost to reading them.

I once rigorously used long-names for everything. But now, I'm working on an algorithm where the operations are what matter, short names actually help me grasp everything at once. As you say, these would be short local variable. Having i, j, k be the standard indexing variable can make some situations clearer.

thinkingeric2• 15 years ago

I use an additional guideline: things that are created near where they are used can be abbreviated more than something that is created 'far away'.

mrfabbri2• 15 years ago

It reminds me of Rob Pike's "Notes on Programming in C", where Pike takes frequency into account as guideline, i.e. "A global variable rarely used may deserve a long name, maxphysaddr say" [http://doc.cat-v.org/bell_labs/pikestyle - Variable names paragraph - a nice and suggested read].

thinkingeric2• 15 years ago

Here is a quote from that essay that says it much clearer than my pithy 'guideline':

"I prefer minimum-length but maximum-information names, and then let the context fill in the rest. Globals, for instance, typically have little context when they are used, so their names need to be relatively evocative. Thus I say maxphysaddr (not MaximumPhysicalAddress) for a global variable, but np not NodePointer for a pointer locally defined and used. This is largely a matter of taste, but taste is relevant to clarity."

jacquesm4• 15 years ago

That's a good rule. I usually declare variables as close to their intended scope of use as I can get them, so for instance, right inside the block where the variable is going to be used.

The temptation then becomes to re-use the name but I avoid that to make it easier to see which declaration belongs to which variable.

Declaring all the variables at the top of a function was a pretty hard to break habit.

jonprins• 15 years ago

I tend to do the same thing. Except, since JavaScript doesn't have block scope, it all ends up at the top of the function.

Which is much more preferable than scattered around the function. Especially due to hoisting[1].

My functions typically go in the order of:

declare variables; declare any local functions if necessary (most of the time these eventually get refactored out to somewhere else, because they tend to be one-off utility functions that can be abstracted); do stuff; return value.

1. http://www.adequatelygood.com/2010/2/JavaScript-Scoping-and-...

giberson• 15 years ago

One subtle spacing issue I find quite annoying that I run into a lot is leading tabs before variable names after type definition.

IE:

  int        anInt    = 7;
  String     aString  = "My string value";
  ClassName  aClass   = new ClassName();

In this example it's not the bad because the typedefs are few, trivial and short and there is actually a leader between the words (.). However, in real code where you have longer class names used in tandem with standard types like int or String as well has some times a dozen definitions--suddenly you wish you had a ruler you can put on the screen.

  int                      anInt            = 7;
  Service_Ups              Svc              = new Service_Ups();
  ClassNamesCanGetLong     variableNamesToo = new ClassNamesCanGetLong();

isleyaardvark• 15 years ago

It doesn't make a lot of sense to put tabs between the variable and its value. Between the type and the variable name makes sense because how often do you try and look something up by type versus by variable name. But when you're looking for a particular variable, you tend to want to see its value right away.

joe_the_user3• 15 years ago

Any kind of fancy formatting is bad because it takes effort to keep it maintained and so it creates a reluctance to change that code. It also creates an illusion of correctness through looking good.

jacquesm4• 15 years ago

There are situations where it really helps though. If you have a series of operations that are unique enough not to be handled by a loop but that change in subtle ways making the changes stand out is an easy way to verify that you're doing it right.

pushtheenvelope• 15 years ago

Personally, I much prefer this way. I never noticed it on smaller projects but now I have to work on a large codebase where some functions become hundreds of lines long. Having variable declarations and assignments structured this way makes it much easier to parse while scanning the code.

akkartik• 15 years ago

My favorite aesthetic on naming things is to try to avoid it. Evidence that this is on the right track:

- Refactoring is often for eliminating temporaries, or for segregating them into their own call.

- A more functional style leads to fewer intermediate variables.

This isn't a rule, or a metric to be optimized to the exclusion of all else. Often the way to clean up code is to get rid of names that don't help you read, coalescing code blobs, until new names occur to you. Then you tease out code blobs again.

Peaker• 15 years ago

Names are great places to put documentation. Documentation in comments isn't as likely to stay up-to-date.

If your names are merely for binding (e.g: f(x) = .. x ..) and don't contribute much, then getting rid of them can be helpful. In Haskell, you can use "points-free" style to get rid of names like that. For example, you can replace:

    f x = 1 + 2 * x

With:

    f = (1+) . (2*)

joe_the_user3• 15 years ago

That's a nice simple explanation of the points-free style, thanks!

But still, I don't feel like this approach would become useful unless/until you reached the point that it could condense a two-line formula into one line (ei, five or six applications further).

I strong suspect that in that case you'd have the kind of formula you only grasp at a glance after you'd working with it intensively for a while.

And this gets into the realm of "write only code" - code too compressed for anyone but it's original author to approach.

iman• 15 years ago

"There are only two hard problems in Computer Science: cache invalidation and naming things." -- Phil Karlton

NickPollard• 15 years ago

I've only heard the version:

"There are only two hard problems in Computer Science: cache invalidation, off-by-one errors and naming things."

jhrobert• 15 years ago

  if (cond) {

or not to

  if( cond ){

That is the question.

I agree that spacing matters a lot. Another interesting idea is that long lines are less readable and that whatever is at the end of a line is less readable than what is at the beginning.

  a = something_long +
  something_else

or not to

  a = something_long
  + something_else

That is another question.

Style matters, develop your own.

aerique2• 15 years ago

With regard to your last example, I think the most important is to be consistent within a project where you put the '+'.

niccl• 15 years ago

In the second example, I find it depends on the language. In general I prefer the top version, but in SQL and some other languages I will usually use the second. That's because I might well want to comment out part of the statement. For example: select col_1 -- , col_2 , col_3 from the_table ; With this approach (the OP's second approach), I can easily comment out a whole line and the rest of the statement will be syntactically correct. The alternative means having to chase around to find the trailing comma (or 'and', or whatever).

But maybe it really only matters because of my recent 'suck it and see' approach to SQL, where I've been exploring an unknown database, trying to find the queries that work...

jsdalton• 15 years ago

Reminds me of the saying (apparently attributed to Claude Debussy), "Music is the space between the notes."

juddlyon• 15 years ago

Naming things is surprisingly difficult - we all have our own mental models. This is an area where pair programming helps. "What should we call this?"

Side note: there's a typo in sentence one, paragraph two: "changnig" => "changing"

Natsu• 15 years ago

If we're going for side notes, am I the only one who noticed that his code would print "z is10"? I even spent a while trying to figure out if he was being ironic somehow, after all that talk about spacing....

bguthrie• 15 years ago

This article rehashes similar points to those raised by Uncle Bob in _Clean Code_. I recommend reading that (much more comprehensive) book for anyone who's interested in the principles behind good code--he makes all these recommendations and more.

Readability and Naming Things

Related Stories