Hacker News Reader

> How hard is it to guess what countCustomers(list) or incrementCustomersScore(list, n) is doing?

When you're as jaded as I am, very.

What is list? What are its elements? Is it a list of customers? Is it a list of something that has a customer as one of its properties? I've seen far too much bullshit in my time to make any contextual assumptions about something called "list".

Same goes for "n". Is that the number of customers whose scores to increment, or is it the amount to increment for each customer in the list? Or something else? What happens if it's negative?

Any time I have to look inside a function (no matter how small) to see what it actually does, I find myself wondering why I must endure this extra cognitive load (and then endure again later when I read the same code but have forgotten the implementation details). And any time I find even mildly ambiguous names, I MUST assume the worst, because people just do stupid things, and therefore I must assume for my own survival that YOU have done stupid things, even if you haven't.

It's very little extra effort to call it modifyCustomersScores(customers, scoreDelta) and eliminate as much guesswork as possible.

Remember: Code is read FAR more often than it is written. Why wouldn't you take steps to optimize throughput on the common path?

Explicit naming is a courtesy. It's developer U/X. It's telling your reader "Yes, I've been there in the trenches. I've seen the horrors. Here's a flashlight to help you on your way."

if questions like "what is list" keep you up at night, maybe switch to a statically typed programming language

thats not the point, the point is that you cant assume that you really know what the function is doing, too often its doing something else thats really hard to figure out without looking closely. Good code will make it so that you dont have to look closely, you can read the variable and method names.

I don't think static typing is a silver bullet here. As I alluded to in another comment a moment ago, I've seen atrocities that were committed in part because someone didn't want to have to go modify a bunch of type references, or refactor the code to accommodate a new type.

Local type inference ("var") can reduce the friction here, but, you've probably still got to explicitly declare types for parameters and return values, so there's always an excuse to be lazy.

I'd say that full-on Hindley-Milner type inference might help, except that I suspect that the folks who do this kind of thing would find a way to create even more chaos in the kinds of languages that have one.

When you're as jaded as I am, names like customerList don't indicate anything. That could be a list of customers, or a list from the customer, or a list that used to have customers and now has god knows what. But if you gave all your variables really long names, now everything either scrolls off the side of the screen or takes multiple lines and I can't see anything.

This is code rot, which is a different problem.

But even code rot can be mitigated somewhat with this discipline.

Which of these changes is easier to justify:

    countCustomers(list)
    incrementCustomersScore(list, n)
    // where "list" is to change type from "list of customers" to "list of sales domains"

VS

    countCustomers(customers)
    modifyCustomersScores(customers, scoreDelta)
    // where "customers" is to change type from "list of customers" to "list of sales domains"

Code is a map to what the computer is supposed to do. Making things familiar and easily navigated just makes sense. Good code requires good U/X, just like good websites require good U/X. It's just something you do to make your users have a better time using your stuff.

I don't even necessarily trust type names anymore, for similar reasons.

Short names are useful when the definition of the name is only a few lines away. If 'n' is defined and then used within 5 lines, you have the definition right there in front of you.

I would invest effort in making the definitions of local variables easy to read, while keeping the names short. (And keeping the functions themselves short so there aren't many locals in scope.)

There problem here is that now you need to scan beyond the function signature to see what the parameters are for. It also makes it impossible for your text editor or IDE to tell you anything about the function call you're hovering over besides 'n'.

The idea is to reduce cognitive load as much as possible for someone navigating your code. Every line the reader has to read increases cognitive load, and slows him down.

To me, this is sort of like saying you shouldn't use pronouns in English because they assume you've read the previous few sentences. It's possible, but it results in rather stilted prose.

There are situations where text needs to stand alone (such as tweets) but I think a function call is too narrow a focus. The body of a reasonably-sized function seems like a more natural chunk for understanding a program.

`i` vs `index` is whatever. `index` is better, but it's not like I'd bash someone for using `i`.

Using `list` is just bad. Your list (probably) holds a set of things that has a name. So name your list that. At the very least, name it after the type of things it's holding. Types are only declared once, but variable names are forever. Having to constantly look up the type of a variable because the programmer was too lazy to name the list of things as `things` instead of `list` is rather inconsiderate.

(Of course, there are times when you would use `list`. For instance, if you're writing a list sorting function, and you actually have zero context more than "yep, this thing is a list".)

Index isn’t going to be consistent when you need a second iterator in a generic algorithm; people just don’t like the sound of jndex. Use “i” and “j” and “k”, or “idx” and “jdx” and “kdx” if you must, but please don’t use “index1” and “index2” and “index3.”

As you say, list might be the best name for a variable if the use context is generic. The same with iterators and such. But you really have to think ahead to keep the names consistent, complicated names work against consistency.

Well, if you combine the two together...

    List<Foo> foos;
    for (fooIndex = 0; fooIndex < foos.length; ++fooIndex) {
        Foo foo = foos[fooIndex];
        List<Bar> bars = foo.bars;
        for (barIndex = 0; barIndex < bars.length; ++barIndex) {
            Bar bar = bars[barIndex];
        }
    }

It would be immediately, visibly obvious if you accidently use `fooIndex` in the `bars` list. Good luck getting that with `i` and `j`.

That, of course, is assuming you even need the indexes. Otherwise you get this:

    foreach (Foo foo in foos) {
        foreach (Bar bar in foo.bars) {
        }
    }

You have more context (in that first example) and so the foo and bar indexes make great sense.

i and j really make more sense (as i and j) when used in their more mathematical connotation: indexes into a multidimensional array/object.

  for (i = 0; i < thing.length; i++) {
    for (j = 0; j < thing[i].length; j++) {
      thing[i][j]; // this is very close to the mathematical use of indexes
    }
  }

Makes perfect sense because i and j are being used to index into the same thing.

i and j would be poor fits for your first example because they don't index into the same thing anymore. You've introduced additional levels of indirection, to rewrite your first example using i and j (and illustrate why this is an awkward construct):

  for (i = 0; i < foos.length; i++) {
    for(j = 0; j < foos[i].bars.length; j++) {
      foos[i].bars[j];
    }
  }

It's not wrong, but it is awkward and unclear as the code grows larger it becomes easier to misuse i, j, and subsequent index variables.

=====

And of course, you're absolutely correct: foreach or equivalent is a better construct. It states the intent of the code, rather than the how of the code. This keeps your code closer to the semantics of your problem specification.

however I would skip j as it is too similar to i. Use k instead.

Well, yes and no. I can see your point, but simplicity and recognisability sometimes are sometimes a trump card.

lst is actually a very good example. If you are writing small functions of less than a screen (which you arguably should be), and you can see that lst is a list of FileInfo, and the code to populate it in a function called GetAllWebConfigsUnderPath, and you have twenty of thirty other types of list generating functions, then seeing lst as the primary thing that gets filled everywhere is comforting and recognisable.

Having said that, having lstWebConfigs and lstAppleFiles and lstUnixFiles might be useful, for example.

Also, I assume you mean "type" as in "the kind of things that it is", rather than its actual type, such as integer, string, etc. lstInteger is largely pointless in this age of IDEs, but lstUserIdentifiers is demonstrably better (You shouldn't compare UserIdentifiers with StockCodeIdentifiers unless you work in H.R.)

Abbreviating as lst is just bad. You saved one character. And now people have to guess whether you meant list, last, localString, or first.

Yeah, sorry. I misread the original "list" as "lst" because that's what's used extensively here, and you're right.

When I said type, I meant type. Your example of "userIdentifiers" instead of "integers" is covered by my statement:

"Your list (probably) holds a set of things that has a name. So name your list that."

Yes. I was agreeing with you in that bit. Sorry I didn't make it clearer.

I don't say you should never use "customers" over "list", but the latter is often good enough. List is a good fit for a compact method which is doing something generic on a list or the context clearly specifies what is in it. It is of course a matter of what you are doing. The point is, that being very specific every time is likely overkill.

You keep saying if it's obvious in context, but context is a name for "one more damn thing I have to keep track of." Which is why I call it inconsiderate; you are forcing other developers to constantly have to build and maintain their mental context of what is going on.

"Oh, great... Here's another `list` variable, let me go see what it is this time."

I disagree. There's practically zero cost to writing "customers" instead of "list". The only time it really makes sense for it to be "list" is when you're writing generic methods that just know it's a list.

> `index` is better, but it's not like I'd bash someone for using `i`.

Thre's strong grounds for saying that `i` is better.

At least in a lot of the code I work with, `index` is most likely to be assumed to mean something akin to a SQL index similar - a data structure or module used for fast lookup.

Whereas `i` is universally understood to be an iteration counter or a position in a sequence. That's a well-known convention that goes back for hundreds of years, and that many (if not most) of us learned before we really learned to program, by virtue of its use in math notation.

That is strong grounds for saying that `i` is likely to be well understood. Which is why I would not even bring it up in a code review. (Unless there is nested looping with multiple indexes, in which case I very much want better names to help prevent mistakes.)

And yes, words can have many definitions. This is where you actually do rely on context for the reader to separate. And I have zero issues with local conventions overriding global conventions. So if you really do have a lot of confusion between whether an integer means an array index or an SQL index, by all means create convention to disambiguate.

(Also, while "hundreds of years" is technically accurate, it's probably not as old as you think. Euler was mid 1700's with his sigma summation notation.)

I'd suggest that `count(customers)` or `incrementScore(goodCustomers, delta)` are shorter, more readable, don't embed type information in the variable name (e.g. what happens if you realise your customers are actually a set, not a list), and don't end up embedding type information in your function name (e.g. what if I want to count employees).

Also, by not including semantic information in the variable, it also requires this to be conveyed everywhere else e.g. your function names. You rightly point out that hopefully there's tight context around this thing (e.g. it's only about customers) and maybe you can leave that out, but over time as code changes and grows in weird ways, this may not always hold.

What do you think?

Embedding types in the method names is a habit of using dynamically typed languages. If the method is private it can be shorter, if it is public it should be a bit more descriptive. With statically typed languages I'd agree with your suggestion, but i'd likely would remove the type info from variables as well.

> If the method is private it can be shorter

Won't other people still need to read private code?

Of course, but the scope is heavily limited. This doesn't justify nonsense naming, but it can be very compact.

To me, if you feel compelled to start putting type information in the variable names, function names, etc., what you're showing is that you really want a type system.

Having types on your API names is a good indicator that you didn't abstract your problem in separable enough concerns.

It does help one turn a bad API into a bad API that will lead to slightly less bugs.

> How hard is it to guess what countCustomers(list) or incrementCustomersScore(list, n) is doing?

The correct comparison is: 1. what is the cumulative time wasted when people guess wrong? 2. what is the cumulative time spent writing out a meaningful name?

When I'm conservative in my estimate of how good people are at guessing my intuitions, I always find that #1 seems to dwarf #2.

My only wish is that tutorials/frameworks would name everything with Foo

like iFoo, or listFoo, etc... When using these, I often dont know whats an Object that cannot be changed, and whats a variable.

Sure you can play around with it, but I feel like I've lost plenty of time trying to understand other's code.

"the context usually defines what is in there" is part of the problem. You really should need to know the context to know what a variable is. Sure "countCustomers(list)" gives you an idea of what list is (well sort of, is list a list of customers, or is it a list of people, some of whom are customers?) But "list.count" doesn't give you any info. The other issue is it makes it difficult to do global searches. And code reviews are more difficult as I may not be able to glean the context from the few lines that show up in the diff. Variable names should be succinct, as long as they need to be and no longer.

It really depends on the team coding conventions. Our team uses 'c' for sql.Connection, 'rs' for sql.ResultSet, and 'txn' for our ORMs transactions, and we do this absolutely everywhere. The short variable names absolutely increase readability. But without the solid conventions it isn't as much of a win.

>It saves a lot of typing

Are you getting paid by least amount of characters typed?

Autocomplete means I type less than six keystrokes for most of my uses of a variable.

“Fewer characters” seems to be the domain of people who place little to no value on good tools. In the worst cases they make choices that are actively hostile to anyone else using better tools.

See also the Toxic 10x-er, who is really a 3x who makes everyone else 2/3rds less effective.

Short variable names like `i` are often the most appropriate. It's a thoroughly understood idiom and to use anything else just because you don't like single letters is just stupid. It's fine if you want to use a language that let's you easily avoid using indexes at all, though. But only if it's idiomatic in that language.