4 ms·

> Hype: "Identifiers should be self-documenting! Use full names, not abbreviations." > Shower: Researchers had programmers fix bugs in a codebase, either with

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

blueprint 4y ago
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.
WalterBright 4y ago
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?
- SmooL 4y ago
  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").
  - ReactiveJelly 4y ago
    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.
  - camgunz 4y ago
    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.
- baby 4y ago
  > Frisco for San Francisco wait what. I live in SF and everybody just says SF
  - WalterBright 4y ago
    I've heard SF, SanFran, Frisco, and Cisco.
    - MajorBee 4y ago
      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.
    - baby 4y ago
      interesting, I'm used to outsiders saying "sanfran" but never heard frisco and cisco
      - WalterBright 4y ago
        Cisco Systems https://thebolditalic.com/don-t-call-it-frisco-the-history-of-san-francisco-s-nicknames-the-bold-italic-san-francisco-5c14348d49c https://thebolditalic.com/don-t-call-it-frisco-the-history-o...
- dhosek 4y ago
  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.
- enasterosophes 4y ago
  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.
ehnto 4y ago
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.
- camgunz 4y ago
  > 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.
  - ehnto 4y ago
    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.
hoosieree 4y ago
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.

blueprint 4y ago

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.

WalterBright 4y ago

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?

SmooL 4y ago
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").
- ReactiveJelly 4y ago
  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.
- camgunz 4y ago
  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.
baby 4y ago
> Frisco for San Francisco wait what. I live in SF and everybody just says SF
- WalterBright 4y ago
  I've heard SF, SanFran, Frisco, and Cisco.
  - MajorBee 4y ago
    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.
  - baby 4y ago
    interesting, I'm used to outsiders saying "sanfran" but never heard frisco and cisco
    - WalterBright 4y ago
      Cisco Systems https://thebolditalic.com/don-t-call-it-frisco-the-history-of-san-francisco-s-nicknames-the-bold-italic-san-francisco-5c14348d49c https://thebolditalic.com/don-t-call-it-frisco-the-history-o...
dhosek 4y ago
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.
enasterosophes 4y ago
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.

ehnto 4y ago

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.

camgunz 4y ago
> 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.
- ehnto 4y ago
  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.

hoosieree 4y ago

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.