Hacker News Reader

Comment by laserlight | Hacker News Reader

> Hype: "Identifiers should be self-documenting! Use full names, not abbreviations."

> Shower: Researchers had programmers fix bugs in a codebase, either with all of the identifiers were abbreviated, or where all of the identifiers were full-words. They found no difference in time taken or quality of debugging.

That's a very weird take on the statement. The downside of using abbreviations is probably dominated by the difficulty of fixing the bug. The problem I have with abbreviations is that they just become another thing that you have to spend your mental resources on. “What is this variable exactly? Oh, I see.” is just wasted effort.

View on HN

Maybe I could get it done in the same time, but I'd be really annoyed, and less certain what things are intended for. An IDE can really carry the burden figuring out what things are, but you're going to lack some context.

Usually it doesn't matter WHAT things are, I need to know WHY you have a variable, and what it's intended use is. That can be explained in the variable name a lot of the time.

I have the same argument against the no-comments evangelists, and wanting to squash all commits into one when they're merging. Yes you can read the code diff, but that only tells you what, not why, something was changed. Why did the API endpoint change? Why do we have to call the payment processor before this event rather than after all of a sudden? Why did the add to cart button move up one div? All very useful information when you have to come back to fix things.

For the no-comments evangelists, I understand the idea is to make the code as self-documenting as possible, and that's awesome, but you can still miss out on the why, and sometimes the Why is entrenched in external business requirements that aren't in the code.

> Why did the API endpoint change? ...

This stuff all feels better suited for a commit message. Conversely if I found all this in code I'd delete it.

I'm an almost never comment person (I use them when things are weird or inconsistent, but otherwise view them as noise) but I've been persuaded by John Ousterhout that code cannot adequately describe abstractions, and you need comments to fill in the gap.

Similarly with variable names, if you don't know i is index, please don't try working on this code. I get some code is a soup of inscrutable variable names and flow control to the degree it looks decompiled, but that's a higher level composition problem, not a "use more nouns" problem.

I also almost never comment code architecture and logic, but code is usually solving some business problem and documenting that in code is just not always reasonable or even possible. Also bugfixes and compat related naming in live software gets you things like fixForObserverOverrideBugIn364

For me it's more about not wasting people's time. Names are opportunities to divulge minor contextual information that you spent time figuring out, and it would be going backwards to then compress that into shortened names.

i for index is fine, but if you have nested loops or multiple loops it gets annoying.

Oh yeah totally get it. I feel like our area of agreement is that whenever you're writing code, you should be writing it to be read and understood, not simply executed. Whether that's through naming, comments, docs, structure, etc.

An example of a comment I'd value is something like a "why bother" at the top of a file doing a lot of in-depth algorithmic work, like a note accompanying a Chesterton's Fence. It makes some sense (though I quibble with this all the time) to design things so as to be as understandable as possible, and then only start optimizing when necessary, and when that happens it's useful to put a "this is pretty complicated, but it cuts CPU time down by 30%. [here](link) are the tests, and [here](link) is the naive equivalent implementation".

People nearly always gravitate towards abbreviations in natural language. The more a word is used, the more likely it gets shortened. LA for Los Angeles, Frisco for San Francisco, Vicki for Victoria, Jay for Jason, Dub for George W Bush, Doozy for Duesenberg, and on and on. Why should programming be different?

Because abbreviations are nice when there's a shared context that is perpetually "in memory" - I don't have to think to know what LA stands for. However, that is not the case when debugging. It is almost certainly the case for the person who wrote the code originally, but it is certainly not the case for the next person to come read it afterwards. IMO code is meant to be read, so I try to never use abbreviations (other than e.g. _i_ as a for loop index, which, given it's pervasive use, falls under the category of "shared context").

I read somewhere, "The length of a variable name should be proportional to the size of its scope".

Usually I don't have long loop bodies, so if the loop body fits in 24 lines, `i` is perfect for the index.

If I'm locking a mutex, doing something, and quickly unlocking it, `l` for the lock guard is fine.

But if it won't fit on screen, it needs a longer name.

And if there's something like a top-level `App` struct, I just call it `a` because its scope is really just `main`, even though its _lifetime_ may be the entire process.

Shouldn't you have some shared context when working on code together, even at different times? Maybe they terms of art, maybe it's a style guide, but there oughta be something.

Like, isn't it fine to change:

    var basicAuthenticationController = new BasicAuthenticationController()

to:

    var ctrl = new BasicAuthenticationController()

I find that if code authors do work upfront to contextualize things for me that it helps tremendously. Like do I need to know at every point that this is a BasicAuthenticationController? Or is this the basic auth module and we're always dealing w that controller? I prefer it when engineers set the table for me like that, it helps me narrow my focus to the purpose of the code.

> Frisco for San Francisco

wait what. I live in SF and everybody just says SF

I've heard SF, SanFran, Frisco, and Cisco.

Kinda going off on a tangent here, but it was a mild "ohhh" moment for me when I first realized that the company Cisco is actually named after San Francisco, followed by a second such moment when I realized that Cisco's logo represents the Golden Gate bridge.

interesting, I'm used to outsiders saying "sanfran" but never heard frisco and cisco

Cisco Systems

https://thebolditalic.com/don-t-call-it-frisco-the-history-o...

Abbreviations that are widely understood are fine. sql_string is superior to standard_query_language_string. On the other hand, I would prefer customer_id to cid in most cases.

When I worked as an analyst in DoD, it was widely understood that acronyms would appear everywhere in everything we did, but also that it can confound a reader who bumps into an unfamiliar acronym if it appears out of nowhere in a report. The caution and best practice was to always give the full name the first time it is used, together with its acronym in parentheses. Then after that you are free to use the acronym as much as you want.

I doubt it would be controversial if programmers adopted a similar convention.

The problem is everyone thinks they're good at naming when they're the one writing the names, but it turns out everyone is terrible at naming when you're the one reading the names.

Names evoke ideas, and this is very subjective. So "self-documenting names" can turn into "misleading names" in a hurry. The name "x" never misleads because it evokes nothing.

How new devs modify the code depends on its names too. So does how we further consume code modules. Architecture and system complexity are virtually emergent from names. So I agree. Kind of a nonsense one.

Reply on news.ycombinator.com