Comment by kstenerud | Hacker News Reader

Comment by kstenerud | Hacker News Reader

Parent Full thread

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

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.

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.

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.

Reply on news.ycombinator.com