

Readability and Naming Things - princeverma
http://www.codesimplicity.com/post/readability-and-naming-things/

======
akkartik
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
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
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.

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

~~~
jacquesm
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
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-...](http://www.adequatelygood.com/2010/2/JavaScript-Scoping-and-Hoisting)

------
jhrobert
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.

~~~
niccl
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...

------
giberson
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();

~~~
joe_the_user
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
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.

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

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

~~~
jacquesm
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
"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
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.

------
bguthrie
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.

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

