9 ms·

Readability and Naming Things

52 points by princeverma 16y ago

petervandijck 16y ago
Good article: things that are complex should have long names, things that are simple should have short names. Like the approach.
- jacquesm 16y 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_user 16y 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.
    - jacquesm 16y ago
      Sure, that's fine, those are pretty close to universal. It would actually be less readable if you suddenly started to use long names for loop variables and such.
thinkingeric 16y 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'.
- mrfabbri 16y 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 http://doc.cat-v.org/bell_labs/pikestyle - Variable names paragraph - a nice and suggested read].
  - thinkingeric 16y 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."
    - aerique 16y ago
      Huh, why not MaxPhysicalAddress[1]? "maxphysaddr" looks like my cat walked across the keyboard. [1] or seperated by underscores or dashes in up- or lowercase wearing earmuffs
      - mrfabbri 16y ago
        for what concerns capital letters, from the essay I cited before [http://doc.cat-v.org/bell_labs/pikestyle http://doc.cat-v.org/bell_labs/pikestyle]: "I eschew embedded capital letters in names; to my prose-oriented eyes, they are too awkward to read comfortably. They jangle like bad typography". As Pike acknowledges this is just a matter of taste.
giberson 16y 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 16y 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_user 16y 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.
  - jacquesm 16y 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 16y 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 16y 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 16y 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_user 16y 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 16y ago
  "There are only two hard problems in Computer Science: cache invalidation and naming things." -- Phil Karlton
  - NickPollard 16y 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 16y ago
To 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. To a = something_long + something_else or not to a = something_long + something_else That is another question. Style matters, develop your own.
- aerique 16y ago
  With regard to your last example, I think the most important is to be consistent within a project where you put the '+'.
- niccl 16y 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 16y ago
Reminds me of the saying (apparently attributed to Claude Debussy), "Music is the space between the notes."
juddlyon 16y 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 16y 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 16y 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.

52 points by princeverma 16y ago

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

jacquesm 16y 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_user 16y 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.
  - jacquesm 16y ago
    Sure, that's fine, those are pretty close to universal. It would actually be less readable if you suddenly started to use long names for loop variables and such.

thinkingeric 16y 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'.

mrfabbri 16y 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 http://doc.cat-v.org/bell_labs/pikestyle - Variable names paragraph - a nice and suggested read].
- thinkingeric 16y 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."
  - aerique 16y ago
    Huh, why not MaxPhysicalAddress[1]? "maxphysaddr" looks like my cat walked across the keyboard. [1] or seperated by underscores or dashes in up- or lowercase wearing earmuffs
    - mrfabbri 16y ago
      for what concerns capital letters, from the essay I cited before [http://doc.cat-v.org/bell_labs/pikestyle http://doc.cat-v.org/bell_labs/pikestyle]: "I eschew embedded capital letters in names; to my prose-oriented eyes, they are too awkward to read comfortably. They jangle like bad typography". As Pike acknowledges this is just a matter of taste.

giberson 16y 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 16y 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_user 16y 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.
- jacquesm 16y 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 16y 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 16y 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 16y 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_user 16y 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 16y ago
"There are only two hard problems in Computer Science: cache invalidation and naming things." -- Phil Karlton
- NickPollard 16y 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 16y ago

To 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. To a = something_long + something_else or not to a = something_long + something_else That is another question. Style matters, develop your own.

aerique 16y ago
With regard to your last example, I think the most important is to be consistent within a project where you put the '+'.
niccl 16y 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 16y ago

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

juddlyon 16y 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 16y 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 16y 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.