
Choosing good names - marcelocure
http://marcelo-cure.blogspot.com/2015/06/choosing-good-names.html?m=1
======
galaxyLogic
The article makes a clear case for keyword arguments, without mentioning it at
all. In Smalltalk you would write something like:

calculateTax: percentage transferValue: value

This has the advantage over the proposed solution that where-ever you CALL
such a method, the meaning of the passed-in arguments is clear ALSO in the
calling context. Just having meaningful names for FORMAL arguments does not do
anything about how the ACTUAL arguments are named, in the (often more than
one) places where the method is called. Meaning, it is hard to know whether a
given method-call has its arguments in correct order without a) Checking the
method-definition for their expected order b) Checking from the calling
context the meaning of the variables you pass in to the call. Do they agree?
Takes some figuring out.

That requires of course that your language supports keyword arguments. In
languages that don't you can simulate them by using a single object as the
only argument. That may seem like extra work but it helps, especially when
there are many "arguments". It also allows you to have default-arguments
without requiring that they are at the end of the argument-list. I think this
pattern is called "Argument Object".

------
benjiweber
You could provide even more clarity by using meaningful types like Money or
TaxPercentage instead of Double.

This would allow you to ensure only valid values are passed and would help
avoid problematic floating point arithmetic :)

~~~
thameera
I guess you mean typedefs and not separate classes for Money, TaxPercentage
etc.

I recently came across a codebase that implement type classes for almost all
types of things it handles and found that to be overkill. Almost always, name
and age can be represented by a string and an integer respectively; separate
Name and Age classes just reduce the readability in your code.

~~~
nhaehnle
In a language that supports it reasonably, the advantage of genuinely separate
types is that the language will prevent you from doing stupid things like
accidentally multiplying to monetary amounts or adding a percentage to a
monetary amount.

Reasonable support here mostly means that you can implement operator
overloads, so that you can define e.g. a Money type that can be added but not
multiplied.

Money handling may not actually be such a good example for this, because you
should really have proper unit testing there anyway. I did work on a codebase
that had types for SI units, and it was quite a nice experience.

------
guiambros
The me the best convention is Linux kernel coding style. I prefer slightly
more verbose variable and function names on interpreted languages, to
compensate the lack of static type checking, but _calculateTaxOverTransfer()_
is probably too much.

 _Local variable names should be short, and to the point. If you have random
integer loop counter, it should probably be called "i". Calling it
"loop_counter" is non-productive, if there is no chance of it being mis-
understood. Similarly, "tmp" can be just about any type of variable that is
used to hold a temporary value.

If you are afraid to mix up your local variable names, you have another
problem, which is called the function-growth-hormone-imbalance syndrome. See
chapter 6 (Functions)._

Source: Linux kernel coding style -
[https://www.kernel.org/doc/Documentation/CodingStyle](https://www.kernel.org/doc/Documentation/CodingStyle)

~~~
vosper
The two examples given in support of short local variables names rely heavily
on convention or prior knowledge. I don't think they're strong arguments for
making short variable names.

Naming the integer counter "i" is convention learned in CS class (initially)
that has become common usage. If you have nested for loops then j, k are often
conventional for naming the next counter variables, though without an
enclosing "i" they would look strange to most people.

Likewise, tmp draws on existing knowledge of /tmp as the location for
temporary data on Unix machines.

~~~
baddox
Relying on convention is a _good_ thing, as long as your team (and the larger
community for that language) is mature enough to have a strong set of
relatively easily discoverable conventions.

~~~
ams6110
Strongly agree. Conventions can produce code that is easier to read and to
write. Certainly to the uninitiated, most of the formulas in a math or physics
textbook look completely opaque. But by following conventions on meaning of
symbols, they are precise and expressive and also easier to write.

------
crimsonalucard
Often programmers instinctively name their code the same way they structure
it: with as much elegance and brevity as possible.

If you think about it, elegance and brevity in naming serve no logical
purpose. When reading names, understandability is the only goal; elegance and
brevity do not assist in this goal. Thus, from a readability standpoint, it is
better for names to be verbose and informative at the expense of elegance.

There are those out there that complain about how verbosity contributes to
increased typing time and the probability of spelling errors, to which I have
to say: Modern dev tools like Intellisense and autocomplete largely eliminate
this type of error. Additionally, if you hate these modern tools, I still feel
that, especially in extremely large and complex code bases, the benefits of
writing clear and understandable code with verbose naming far outweigh the
benefits one gains when using brevity in naming.

------
mtviewdave
I would have called the function "calculateTransferTax". It's shorter while
providing the same meaning.

Also, the "tax" argument is the tax _rate_. "tax" in this instance I would
expect to mean the final amount. So I'd call that parameter "taxRate".

(And I'd use ints for everything, of course)

~~~
thameera
How would you use ints when there's division in the code? I've heard it's
usually better to prefer ints to floating points, but in my limited experience
I've found that it's easier said than done.

~~~
JamesMcMinn
Using floating point arithmetics for currency is just asking for trouble:
[http://stackoverflow.com/questions/3730019/why-not-use-
doubl...](http://stackoverflow.com/questions/3730019/why-not-use-double-or-
float-to-represent-currency)

------
rhaps0dy
I guess the verbosity of the method's name is actually good in this case?
Since it makes the function so much clearer.

I am never sure how much to abbreviate a name, but I guess if it's not going
to be used much it can be long without problems.

~~~
bdavisx
If you're using a modern IDE, you shouldn't have to ever type the name out
after the first time. I almost never abbreviate anything.

~~~
marpstar
When I first started using Objective-C, I noticed how verbose the signatures
were when passing messages, but really liked how it read when you were
scanning the source.

After that, I stopped giving a shit about how long my identifier names are and
just make sure they explain in a direct (but concise!) way what that method
does or what that variable is.

------
JamesMcMinn
In this case, I'd argue that the names are still bad for a couple of reasons.

Firstly, it's too verbose - a nice middle ground would have been better:
calculateTransferTax(Double transferValue, Double tax). It's fairly clear what
the tax is being calculated over.

Secondly, I'd say that "tax" is a bad name for the tax percentage since it
doesn't describe that what actually is (the percentage / rate of tax), and
since it's a Double, I'd expect it to be "0.2" for a 20% tax rather than 20.0
which appears to be what the method would actually expect.

------
jfaucett
I agree with this post in the general sense, still I think you can go way
overboard with this.

If you take as your goal this: "understanding what this piece of code does 1
year from now", as opposed to "I should name these variables and this function
fully and correctly" then I think you'll do a lot better each time. There are
numerous places where I can more quickly and easily consume "i" as apposed to
"someArrayIndex", or "fname,lname" instead of "firstname, lastname", etc.

------
KillerRAK
When it comes to code readability, and ultimate reusability, I believe
renaming variables is where most time refactoring is best spent. Not only does
it encourage better naming, but if the naming or paradigm model is off, it
encourages better design.

~~~
logn
I'd vote for removing dead/useless code, reducing scope/visibility, making
things immutable, and running an auto-formatter. In the case your code is
being re-used by outsiders, in an API or something, yeah bad naming ends up
being awful.

------
confiscate
thanks for the post.

yes taking an extra 10 seconds to name a function in a more clear way could
probably save hours of frantic reading and cross referencing for another
engineer down the road, especially when fixing urgent bugs/issues

~~~
_asummers
And please make sure the words are spelled correctly in your public API. A
library we use at work has a typo in the word "Acknowledge" where it is
"Acknowladge". Drives me up the wall every time I see it.

~~~
confiscate
ya this drives me nuts. Especially when the "autocorrect" word checker inside
the IDE complains about the typo and keeps showing a red squiggly line, for
code that is in another library that I am not supposed to change within the
project in the IDE. Drives me nuts

------
YokoZar
I'm a big fan of good descriptive names, but in practice when I run into a
lint-enforced 80 character line limit names are the first thing to suffer.

------
revelation
Well thank god we fixed the naming, that will surely help when someone comes
looking to find out why all the amounts don't add up.

~~~
tgaussman
Indeed.

Looking forward to the follow-up post, "Choosing good types".

