11 ms·

Names should be as short as possible while still being clear

85 points by benhoyt 3y ago

spicyusername 3y ago
I'm not knocking the article, but endless aesthetic discussions like this are one of the reasons why I can't wait to leave the industry. The very definition of bike-shedding. compare acquire and take_ownership Who cares!? Those are both great names for a function... If you put 10 software engineers in a room, you'll get 10 different answers to any question. Every company you work for will be filled with endless "smart guys", ready to spring in to action and nitpick you to death about arbitrary things. It's exhausting. We need more languages that come with rigid rules for things like style, so we can stop wasting time and get on with solving problems.
- kspacewalk2 3y ago
  While I share your frustration, I think leaving the industry because of it is an overreaction. It's fairly easy to just ignore the aesthetic discussions and focus on solving problems. Whenever someone brings up renaming a function from perfectly_good_name_1 to perfectly_good_name_2 in code review, I immediately agree without discussion and move on with my life.
  - spicyusername 3y ago
    Indeed, indeed. Maybe a more accurate phrasing would be, "Can't wait to retire and do literally anything else with my time, including writing programs with which I answer to no one about coding style.", Hah.
  - 000ooo000 3y ago
    >It's fairly easy to just ignore the aesthetic discussions and focus on solving problems. You probably know this but for discussion's sake: in many modern forges, your pull request can't be merged unless the comments have been resolved/closed. So you basically cannot ignore these "feedback" items; you have to engage the comment whether that means actioning it or refuting it. I currently work with the worst pedant I've encountered in my career to date, and I can empathise with wanting to leave the industry.
    - Maxion 3y ago
      > I currently work with the worst pedant I've encountered in my career to date, and I can empathise with wanting to leave the industry. I have one of these too, one of my PRs received a comment on the third round of review about correcting a minor typo in a comment that was made years ago by someone else.
      - gwright 3y ago
        FWIW, we started using https://conventionalcomments.org https://conventionalcomments.org a while back and found it to be a useful tool for making it easy to communicate what is an issue that needs to be fixed, a suggestion to consider, or a nitpick to optionally ignore. It is still just a tool and does require the team to buy-in and utilize it, but we've found it helpful.
      - jrd259 3y ago
        If the comment was in code you touched, this seems right. Typos affect searchabilty. If the typo was outside (but close to) the block you modified you shouldn't be required, and the team ought to have rules of engagement to state this.
    - mannykannot 3y ago
      It would be better for all if the pedant left the industry, but they typically have too much self-worth invested in an inflated perception of their expertise within it.
    - SCdF 3y ago
      What is a forge in this context? Is that a name for a code repository website? I'm unfamiliar. Regardless, I think that's just a function of your team and your dynamics that you've built up. On the current team I'm on we for example don't require this (at least on GitHub its configurable), there is an understanding of nits, how to declare them and what that means, as well as an understanding of using request changes vs approve and so on. We've built this up by having discussions about what the purpose of reviews are (eg making sure your code is understandable by someone other than you), having a common understanding that perfect should never get in the way of good, etc. We regularly have retrospectives where, if we were having issues with really bad pedantry, I would hope it could be brought up.
- Aardwolf 3y ago
  Automatic style formatters solve a lot of this discussion. Not all, such as the naming example here, but at least things like whitespace and line wrapping never have to be a discussion point again if you have the rule that whatever the style formatter outputs is what you use
- 3cats-in-a-coat 3y ago
  Bikeshedding is prevalent in every popular area of human study, because it's easy to talk and write about. It's not representative of what matters to those who get the job done.
  - ozim 3y ago
    Bike shedding is not the problem here. Attitude is, if I can argue with someone and have it in a fun productive way - even if we don’t tackle most important thing we should work on at the moment - it still might be valuable. If I have to deal with smartass that nitpicks on variable names, he wastes my energy and any will to do further work for the day or if it is more heated and goes over some “Astro architecture” might even burn my willpower to do any work till the end of the week.
    - 3cats-in-a-coat 3y ago
      I don't mean to bikeshed, but you seem to be describing bikeshedding. Bikeshedding in practice is often accompanied with aggressive arguments because some (or both) sides just really want to be right about something, as a way to offset their real worry, despite neither choice solves their real problem. Although I guess it could also be a pleasant chat, why not. Consider for example the bikeshedding society did on whether to distance 1.5m or 2m during COVID, and how precisely and how long to wash their hands. We had a ton of those. When people feel out of control they want to own a decision that makes them feel like they're back in control. Programming is complex at scale. But bikeshedding about how many characters our lines, how many lines our functions, and how to name things is always there for us to argue about. Oh and whether a class is truly single responsibility, that's an evergreen.
      - jjk166 3y ago
        That's not bikeshedding. Bikeshedding is focusing on an unimportant but familiar aspect of a complex project specifically because one lacks the technical knowledge to discuss the important parts. Bikeshedding might involve nitpicking, but it doesn't have to, and one can nitpick without bikeshedding. Maybe a code reviewer is genuinely so inept they can't understand anything more complex than naming standards, but far more likely they're just a bit neurotic with regards to following standards.
- 000ooo000 3y ago
  >nitpick you to death about arbitrary things Yep, it gets tedious. It really grates on me when reviewers are willing to die on a hill over some minutia while the codebase is in tatters. Arguing over extremely minor duplication while there exists two, active, physical copies of an application in separate repos (a real example) is the most pennywise poundfoolish waste of time and it drives me crazy.
  - b112 3y ago
    I once spent 8 months merging a codebase with almost every single function duplicated three times, and all that was required for each (most of the time) was another parameter, one conditional in function, and all 3 could be merged. So I did that! And at the same time cleaned up the code, fixed bugs, and adding required new functionality, and all while merging in constant change from the main codebase. After reducing a 1M line codebase to 280k lines, when almost done, after that 8 months, I was asked "how much longer". My response of "a month for testing" was apparently too long for the new manager, who turfed all those fixes, including the new functionality. And I wasn't even behind schedule, I was ahead. Once abandoned, everyone just copy and pasted my changes... in triplicate, into the old codebase. Which took 3 months, instead of 1. Bah. A year of my life wasted.
    - glenjamin 3y ago
      This is a great cautionary tale about what happens if you don’t continuously integrate changes in an incremental fashion.
      - b112 3y ago
        It's a great cautionary tale of management dumbassery. (yes I am still bitter)
    - 6keZbCECT2uB 3y ago
      Spending 8 months when the business value at the end was mostly improved velocity doesn't sound likely to be a good tradeoff, especially if this is done as a big bang effort which either succeeds holistically or fails. You might have better success in the future by finding ways to integrate maintenance improvements incrementally.
- diegoperini 3y ago
  I wonder if there are linters that can check if a method/function name starts with a spell-checked English verb.
- matwood 3y ago
  I don't consider myself a great programmer, but I do think I do two things well. One is solve problems. Like a dog with a bone I become obsessive about figuring something out. The other is I don't care about style, and will happily fit the existing style. For me, it's consistency above all else. I agree completely with you that arguments around style are exhausting.
  - JohnFen 3y ago
    > For me, it's consistency above all else. Entirely this. I have a preferred style when I'm writing my own code. When I'm writing code for someone else, though, I will roll with whatever the house style is[1]. I just want consistency and predictability. Once I know the naming scheme, I should be able to take a really good guess as to what any given function or variable name is by knowing what they do, and vice versa. [1] I consider it a red flag if a company doesn't have an established house style. It matters not what the style consists of, only that it exists and is mostly adhered to.
- draw_down 3y ago
  [dead]
- zajio1am 3y ago
  > Who cares!? Those are both great names for a function... The source code has two purposes - to be processed (compiled/interpreted) by software, and to be read by humans. While it is relatively clear what is considered good code for the first purpose, it is harder to say what it is for the second one. An essay could be written in an elegant style or be full of clumsy wordings and hard to understand sentences, despite having the same meaning. The same is true for source code.
- bborud 3y ago
  Naming things sensibly and doing so consistently is pretty important in designing software because names are relied on to convey meaning. Sensible naming helps people. Bad and inconsistent naming confuses people. Naming matters more for interface types and APIs than for local variables. "acquire" and "take_ownership" might be equally good names for an operation, but you should pick one and stick to it throughout the codebase. And it would make sense to poll other people about what they think is a good name. Especially if you don't really care one way or another. Other people may have valid perspectives or they may just be better at expressing meaning through names. You can't really nail everything down in the official style guide for a language without it becoming baroque and oppressive. If you want to avoid bikeshedding, have a process in place for choosing naming conventions. Name someone as the arbiter. If consensus cannot be reached within a reasonable amount of time, the arbiter decides. It might help to keep a record of naming choices so people understand the reasoning behind why certain practices are chosen. Most programming is a social activity in that multiple people will have to deal with the code. Not caring about something as essential as naming, and wanting to avoid effort because you don't care, can be seen as a kind of anti-social behavior. On well functioning teams I've worked on, naming tends to not be a big issue because over time a team develops a common vocabulary. When in doubt, ask someone else on the team how they interpret a name.
  - coffeebeqn 3y ago
    I agree that consistency is what’s important. If almost everything in the codebase roughly follows the same API then it takes less effort for people to use the various parts
- Kapura 3y ago
  I agree that "Who cares!" should be the default response here, as long as it's clear, but I think some folks (especially in engineering) think that "more rules = more clear," or "if we encode all of this information in the variable name, the variable name will always be clear," which is an error in thinking this particular article seeks to correct. I have actually been in the throes of battle with co-workers over relaxing our variable naming standards because they are too damn prescriptive, which (in my opinion) reduces code clarity, while also setting up conflicts between those who think code should be as clear as possible in the file versus those who think that we should follow the standard even though we know it to be flawed and produce overly-verbose code. My core argument is very much "who cares as long as it's clear" but having a specific piece of ammo where I can say "here are several arguments specifically against our current style" may convince some of these folks to loosen up a little bit. The bike-shedding is indeed ridiculous; going back and forth in Swarm for days over names for code that has fundamental algorithmic flaws. Awful stuff.
- drewcoo 3y ago
  > If you put 10 software engineers in a room, you'll get 10 different answers to any question. Again with the hypothetical dichotomies!
  - Joker_vD 3y ago
    In my experience, getting N software engineers in a room produces exactly N different answers only if you don't allow them to debate further. If you do, the upper bound on the number of different answers seems to be is at least 3N.
- halfnormalform 3y ago
  The latter is probably a better name if there are other functions involving "ownership" (give_ownership, split_ownership, etc.), but otherwise you're right.
  - squirtlebonflow 3y ago
    Yep, I've seen situations where the programmer goes for brevity, and then runs into problems in the future when they want to "be consistent" take_ownership -> acquire (fine at first) give_ownership -> unacquire (not even a word) split_ownership -> halfacquire (complete nonsense) then there needs to be a way to split ownership other than an equal 2-way split and you're fucked. I haven't seen this exact situation, but I've seen stuff like this. And sometimes, I was the programmer. Names should be as short as possible while still being meaningful AND keeping in mind future work requirements. On a tangent, I'm always frustrated when as a developer, I don't learn much about the actual business. There's always a situation down the road where if you had known what the company was planning on doing in the next quarter, or couple years, you could have saved everyone some work by doing things differently.
    - cperciva 3y ago
      unacquire This reminds me of when some code was lightly edited to remove references to "master" and "slave", only to end up with a function "enminion".
- Shrezzing 3y ago
  [flagged]
- chinchilla2020 3y ago
  Yeah it is unfortunate. Ever dealt with a rotating code review that passes through multiple hands? It's funny watching the principal architect and technical fellow ask me to refactor my code again to remove the changes that the other one asked me to make! I spent a month in one such code review. No wonder management hates listening to engineers. If we have a good point to make, they ignore it because of the last 3 engineers who wasted time with stylistic, pedantic arguments.
- ecshafer 3y ago
  A particular gripe of mine is the tendency for some code reviewers to nitpick code golf solutions that don’t really improve clarity, maintainability, or quality (and might arguably reduce them). Going from 40 characters to 30 characters for a functionally equivalent statement isn’t a win worth mentioning in my book.
- soligern 3y ago
  I mean we have AI that generates both the function and an appropriate name for it. If you lean into that paradigm, all of this is a waste of time.
- geodel 3y ago
  It is more of software self-actualization. Just like human would need food, water, shelter, before they move on to top of pyramid. I agree software need to be basic error free, compilable, buildable and deployable before naming and structuring aesthetics becomes important. > Who cares!? Those are both great names for a function... Now the author has written many good quality working software systems, it is natural that they want to talk about next level things.
- omoikane 3y ago
  What we used to do is announce in our team chat: "anyone around for a round of bikeshedding? I need to name a thing". The thing being named is usually not user facing, so it was more of a team building exercise than anything related to compliance or style. We would get it done in a few minutes and never discuss this name again, because we already had this discussion. The actual names that came out of these exercises are generally pretty good, and often a shorter name would win over a longer one.
  - JohnFen 3y ago
    > "anyone around for a round of bikeshedding? I need to name a thing" I have to come up with many names for things in code every day. I can't imagine the slowdown having to workshop every name would incur...
    - Shaanie 3y ago
      I'm sure the names have different importance, though. A local variable name in a small method probably barely matters, whereas the name of a variable in a widely used external API matters quite a lot.
    - omoikane 3y ago
      This is the kind of exercise can be done in the background while waiting for stuff to compile. It's also not for trivial things like private or local variables and such, so not really a frequently occurring speed bump. An example would be a set of enum names that I need to share with my teammates, where it might be a lot of hassle to replace them all if we don't decide on proper names now, but any set of names would work.
- datavirtue 3y ago
  Hmmm...no mention of business domain language. The main reason I want to leave the industry.
- npsimons 3y ago
  > We need more languages that come with rigid rules for things like style, so we can stop wasting time and get on with solving problems. This is where I'm at now. Decades ago, I was an "only spaces, no tabs" guy. Still am to an extent. But what made me more open was realizing it wasn't spaces or tabs specifically that mattered, only that code is readable, and consistently formatted code is more readable. Seeing things like `gofmt`, which mix tabs and spaces, and comes with the language? Your debate about spaces versus tabs is over, now we can get back to tackling real problems, and your code will be rejected at CI if it isn't run through the standard formatter. Same thing with `black` for Python. Above all else, be consistent. I can understand hate for "standard" language libraries that have functions with wildly different naming schemes or input and output arguments that aren't consistent - those should DIAF (looking at you, PHP "standard" library). But as to the names themselves? Doesn't particularly matter much. Unless you're the Bruce Tognazzini of API design, you probably don't have anything of substance to back up why it should be "make_" versus "create_".
  - sdfghswe 3y ago
    > Above all else, be consistent. Aren't you still doing the same thing though? You have your arbitrary rules and they're absolutely truths... until you change your mind about them. Except before the rule was "only space no tabs" and now it's "be consistent"?
    - npsimons 3y ago
      Given how many people here are disagreeing except on "be consistent", I feel I'm in good company in having that as my rule. I'm not being inconsistent, I'm learning, growing and adapting. "Strong opinions, weakly held." But yes, "A foolish consistency is the hobgoblin of little minds." The question is, what is "foolish"? I'm arguing against things like `strpos` and `str_rot13`. I'm arguing against having similar functions where argument order is inconsistent. These are the sorts of things that slow developers down and force them to check the documentation every time just to make sure they aren't introducing bugs by default.
      - 3y ago
- benhoyt 3y ago
  Not surprisingly (as the OP), I disagree. Good names help people understand concepts; bad names confuse. Choosing good names is not merely aesthetics, it's bringing clarity, meaning, and culture. That said, in this particular case, I think Russ could have chosen a better example. Neither "acquire" nor "take_ownership" are terrible. But when you're a language designer (like Russ), the names you choose shape people's code and their thinking for the next 10, 20, even 50 years. When you're a library designer (many of us are), it might only be a few years, but still. I think as code reviewers we should take this as seriously as the context demands: for internal names and local variables, it's not too important. For public API names, very important. For language changes, extremely important. Some good quotes from Bob Nystrom, author of "Crafting Interpreters": "Names are the structure we impose on the formless sea of bits that is computing." http://journal.stuffwithstuff.com/2016/06/16/long-names-are-long/ http://journal.stuffwithstuff.com/2016/06/16/long-names-are-... "For me, thinking about names is inseparable from the process of design. To name something is to define it." http://journal.stuffwithstuff.com/2009/06/05/naming-things-in-code/ http://journal.stuffwithstuff.com/2009/06/05/naming-things-i...
  - spicyusername 3y ago
    I don't disagree that things like function naming are important. I understand that it's important to think critically about the philosophical North stars of your work. This is precisely what it means to be an "expert". I appreciate the work you're doing adding your voice to the discussion. That being said, it doesn't change the fact that, for me, it's tiring working in a profession where nothing is "real". There is never going to be an end to these kinds of discussions, because everything is abstract, relative, and ever-changing. Unlike many other professions grounded in the limitations of physical reality: carpentry, civil engineering, hair cutting, etc, Software Engineering is a house of cards of artificial abstractions. The tools and architectural patterns are mostly free from physical constraint, so they can change at will, and they do. What is "good" is highly dependent on context, and in our case that context is fluid, changing along every dimension all the time, making it very hard to establish a shared understanding of any given problem. This translates into a work culture where there is always room for debate about what to do, since there is almost never an objective best next step. And debate we do.
- toss1 3y ago
  >>Who cares!? Serious devs care. I was once at a software conference where Bjarne Stroustrup was givnig some presentations, and in the after-session questions, I thought I'd ask about something that had been bugging me about software design in general — I'd found myself spending what I thought might be excessive time to designing naming systems for the projects I worked on, and I wondered what he thought about spending time on naming conventions. With no hesitation, he said "Not at all, naming is very important", and very useful to get right up front, even for solo projects, as good clear naming helps speed the entire building and maintenance. So, yes, both "acquire" and "take_ownership" are relatively synonymous, but one will clearly be better and more consistent with the other in the context of your naming system. And this will matter to at least some serious devs. (But YMMV; if you have tried it a couple times and found it doesn't help you a bit, then you probably shouldn't spend more time on it)
- Pannoniae 3y ago
  "We need more languages that come with rigid rules for things like style, so we can stop wasting time and get on with solving problems." I have the complete opposite opinion. Most software engineers are obsessed with style, and I don't think accommodating it is the right solution. I think the right idea is just not enforcing any stylistic rules at all (while obviously keeping the readability and maintainability-related rules) and just let everyone write code how they want, while forcing them to tolerate other people's coding, naming, brace placement, etc. styles.
ape4 3y ago
Since fetching webpages is very common we know `send_get_request_and_receive_response(url)` is wordy. Of course you need to get the response. But in some other area it might be obvious so naming the function with more words could be useful.
cwbrandsma 3y ago
There are only two hard problems in computer science: naming things, cache invalidation, and off by one errors.
- ozim 3y ago
  I think one problem with first problem is that names are not going to live forever just as the code. Lots of times code will be scrapped, a lot of times code will just run and no one will ever mind changing it. So I’d say amount of time invested in naming won’t payback.
  - erik_seaberg 3y ago
    It’s very hard to change stuff that has grown beyond your control. Local variable names? Sure. API names? That’s a major version break. Correcting the “Referer” header? Unthinkable for 27 years and counting.
- hinkley 3y ago
  After you fix a few cache invalidation bugs, you realize those problems are mostly about identity, and identity is just another form of naming things.
- proto_lambda 3y ago
  There are only two problems in computer science: we only have one joke, and it's gotten old.
  - bcrosby95 3y ago
    There are 10 problems in computer science: we only have two jokes, and one of them is bad.
    - zhte415 3y ago
      What about the other 14?
    - 3y ago
boringuser2 3y ago
Using Golang as an example of naming conventions is questionable - this is a language where single letter variable names are idiomatic. I feel like the author missed the obvious; a name should reduce cognitive load as much as possible. Length is one factor that is relevant to this goal, but not the only factor. When a name is too long, this is usually a design issue, not a stylistic issue, i.e. writing Swiss Army functions. Also, takeOwnership is not inferior to acquire, it's just about a wash.
- hinkley 3y ago
  You can lead a developer to cognitive theory but you can’t make him think.
hahn-kev 3y ago
Just define clear. Clear to you? Or me?
jacknews 3y ago
Is this news? Who said naming was difficult? Obviously all you need to do is make names as short as possible, but no shorter! Simple!
- jncfhnb 3y ago
  You got it, j3!
natch 3y ago
>”… Make every name tell.” >That last sentence is poetry. It’s a borrowing from Strunk & White, “make every word tell.”
mpolichette 3y ago
I tend to agree, however, I typically tell people that if you see longer function names, you should watch out for complexity. In fact, if I have to write some overly complex code that I can’t isolate for some reason, I will usually try to show it in the names being extra long.
JorgeGT 3y ago
The "clear" part is often the issue. My favorite example: - In Mathematica, if you want to plot a vector field, you use VectorPlot[] - In MATLAB, you use... quiver(). You know, because it holds a lot of arrows. Short and clear, eh?
- njovin 3y ago
  "Clear over Clever" is a pretty simple rule that helps avoid this type of thing.
- appleflaxen 3y ago
  Super clever. Very unclear to anyone who is new to that functionality, though.
- dredmorbius 3y ago
  There's a possible higher-order argument for `quiver()`: the name is idiosyncratic, and sufficiently enough that it might tend to get remembered, which is useful for however many more minutes humans are actually writing code in this world. As contrasted with "VectorPlot": was that "VectorPlot", "VectorGraph", "TensorPlot", or "PlotVector"? "quiver" is short and sweet and slightly unusual but also conceptually related in a sense to the function. I'm not saying that "quiver" is the better name, though I'm offering some arguments as to why it might be.
- npsimons 3y ago
  > - In MATLAB, you use... quiver(). You know, because it holds a lot of arrows. Short and clear, eh? "Shaka, when the walls fell." Sure it's poetic, but WTF do you mean?
TheDesolate0 3y ago
[dead]
jlund-molfese 3y ago
Properly communicating when a requested change is optional is actually one of the most important code review skills you can have. By default, developers assume that a requested change is mandatory. So as a reviewer, it's up to you to explain the difference between a change you're suggesting because it's more concise to use a list comprehension instead of a loop vs a change you're requiring because the change list introduces a race condition that will cause customers to lose money. If you do that, you'll make everyone you work with happier
- rsyring 3y ago
  We prefix any comment or request with "nit", as in "nitpick" when the reviewer knows they are being picky but it's still something worth mentioning. The coder in that case knows they can ignore that without consequence if their preference or perspective is different. The reviewer also knows that and doesn't feel bad if that advice is ignored. It's been helpful for me because I'm a picky reviewer and feel compelled to mention things that my years of experience tell me are "wrong." But I've also come to realize it's often not wrong, just not as good for potentially non-obvious reasons. But my devs will never learn the potentially "better" way if I don't point it out. So "nit" gives me a way to communicate and teach without the pressure of the dev needing to make an immediate change.
  - jlund-molfese 3y ago
    Same! I also, if I notice I'm leaving a lot of constructive comments, deliberately try to leave some positives ones too. Like "Nice! Glad we're adding typing here". Just as important to promote positive habits as discouraging negative ones.
hinkley 3y ago
Every code base where naming still matters is a code base that is sprouting new functions. What was “clear” two years ago may be unclear today because we have four times as many functions. Via the pigeonhole principle, there are no short names that are sufficiently clear, and as X goes to infinity even the medium ones become problematic. Use a modern IDE with autocomplete. Try to make the beginning of your names as unique as possible. Few people will have to type in the suffixes. Used to be we would ask other developers what book they would buy all of their coworkers. Answers have changed over time, anything from Brooks to Gamma. But for my money, I would buy them a thesaurus. If you use the same word in two places in the code, they should be sharing code and data structures. If they don’t, you should use a synonym. Never recycle names, and be sure you aren’t recycling. Many people are wrong here, claiming two things are the same but with no code shared, and in many cases I’ve seen, using two different definitions of the same word.
- deleted 3y ago
  [deleted]
natch 3y ago
The hard part of naming is none of these things. The hard part is dealing sensitively with snowflakes who think naming doesn’t matter and instead of saying this to your face, they privately have conniptions trash talking you behind your back when a minor improvement is suggested. They’ve made it so that naming cannot be discussed. If you see a horrendous name and suggest an improvement, there’s no overt response, but later you hear from your friend that the poor namer is accusing you of wanting to die on a hill. Dude. It was just a suggestion. And it was labeled as a nit. You don’t have to take it, even though we’d be better off if you did. So I’ve all but abandoned ever suggesting improved names, unfortunately. Being a good team player is more important. I name my stuff well, but what others do is up to them.
throwawaaarrgh 3y ago
Naming things should be as short as possible while still being clear, unless the context of the situation makes a longer name solve some other problem. Naming things should be short as possible while still being clear, unless making it longer helps something else. Name things short as possible while still clear, unless longer helps something else. Name short as possible while clear, unless longer is better. Name short and clear, unless longer better. If longer not better, name short & clear. if_longer_not_better_name_short_clear ifLongerNotBetterNameShortClear
6keZbCECT2uB 3y ago
This comes into tension with making names as clear as possible while still being short. Frankly, I don't find coming up with short names for things to be easy, let alone good names even when taken to the extreme. Whether something is too short depends on your context. requests.get might be ambiguous for someone who has never seen the code base before, but will quickly get obviously with a little exposure, so does the code base have dedicated maintainers? The skill of good naming isn't distributed evenly and OP's names are pretty good, so I'd be happy for them to come along to my code base and rename things as long as it was within other constraints (not consuming too much time, doesn't break api, etc).
stronglikedan 3y ago
Well, of course. This could also be said as "use long names when short names can't be clear enough." Don't be afraid of long names since we have modern IDEs with competent auto-complete. Also, long names go a long way when searching a codebase.
crazygringo 3y ago
> However, I think the more common mistake is using names that are overly long. But the most productivity-sapping mistake is names that are too vague. The idea that "names should be as short as possible while still being clear" is a truism I don't think anyone disagrees with. But it's a balance that nobody ever perfectly gets right. So if you're going to err, it's better to err on the side of clarity rather than shortness. E.g. lines like: fetcher = repolib.IndexFetcher(args.arch) counts = collections.Counter() for file in repo.files: Would be better as: repo_fetcher = repolib.IndexFetcher(args.arch) file_counts = collections.Counter() for repo_file in repo.files: It's far more helpful when a line of code tells you what it's doing not just in terms of programming logic but in terms of the purpose of the code, the contextual nouns and verbs. It saves a lot of mental effort when reading and debugging.
- contravariant 3y ago
  If we're debating style anyway I'd argue using agent nouns as a class name is a worse offence. Compare index = RepositoryIndex(args.architecture) statistics = RepositoryStatistics() for repository in index.retrieve_repositories(): for repository_file in repository.files: statistics.increment_file_count(repository_file.name) This is still mostly equivalent to the original, but a lot easier to read and pretty much every word removed from the name can be inferred from the type. It can be made even less verbose but at this point there's no real need.
  - jimmaswell 3y ago
    No one was ever hurt by a noun in a variable. Longer and more descriptive is fine.
- classified 3y ago
  There are two hard things in software development: Cache ivalidation, naming things, and off-by-one errors.
bborud 3y ago
Another place where naming matters, but for slightly different reasons, is on the command line. If you are naming a program that someone is going to spend much of their time running from the command line, it is nice if you put some thought into how the binary is named. For instance. I've never been able to understand why something like `systemctl` could be so clumsily named. If you have to do sysadmin work, sometimes you will be using the command a lot. If we ignore the fact that I see more and more people typing out entire commands without the use of completion, `systemctl` lacks a short, unique prefix and ends up being quite awkward to type. On my system `sys` is the prefix for 26 commands, and `system` is the prefix for 24 commands. So I end up having to type 7 keystrokes to type systemctl on my system with completion. Sure, I could alias it, but then I'd have to replicate it everywhere, plus I'd be forming habits that just cause more frustration later. Another way to fail is to choose a prefix that has bad typing flow. For instance I wrote a program that has the prefix "aq". Try to type it. Awkward, isn't it? (If you don't think any of this matters, perhaps you shouldn't be the one to pick names for programs that are run on the command line).
jjk166 3y ago
IDE space is free. Copy and pasting a long string takes no more time or effort than a short string. What you stand to gain from shortening a name is trivially small compared to the risk of making a name too short, potentially leading many people to each waste time trying to figure out what you meant. The author's real problem is not about an excess of characters, it's that names are often long because they include redundant or irrelevant information. Still an incredibly minor issue, but there's some legitimacy to that. Better advice would be to keep names informative.
- thfuran 3y ago
  But the visual field is finite and filling it with fluff doesn't help anyone.
  - jjk166 3y ago
    Your field of view can be moved to sweep over an infinite area. Again, including fluff might not help but it's infinitely preferable to not including something important.
mcpackieh 3y ago
Sure, brevity is the soul of wit and all that. Just so long as you don't go dropping letters from the middle of words because you're going for the unixy aesthetic. That style is an anachronism from an era when symbol length was limited, it doesn't belong in modern code.
fastball 3y ago
My top priority when naming things is discriminated grep-ability: if/when I want to refactor my code and find all occurrences of a certain function call, will this name allow me to do it in a way that is distinct from other names? After that I mostly agree with the author that short and clear are the next two priorities.
- lolsal 3y ago
  I have found myself thinking about this as well the more my career matures. It’s a great thing to consider.
asimpletune 3y ago
Swift is one of the only languages that actually makes long names work. Rust's flavor of variable shadowing is a great way to support developers to keep names short.
JoeAltmaier 3y ago
What goes around comes around. We had naming conventions that produced succinct names. They became denigrated and shunned (for no good reason) - use long descriptive names! Now we see that was a bad idea - longer names just allow for more wasted words and are actually less descriptive. Some kind of social or algorithmic convention makes them quicker to parse and understand. I suppose some compromise will be proposed one day. Maybe a prefix to classify the method name, then some short description. Or even an IDE convention to pop up a short description for method names to allow clarification in-situ.
javier_e06 3y ago
Ed, says the variable name is too long. Sebastian says is too short. Waldo is not sure. A variable name should be easily inspected across the whole project using grep from the root directory of the project.
JohnFen 3y ago
> Some developers do use names that are too short. However, I think the more common mistake is using names that are overly long. I agree 100% with this. Overly long names are very painful to work with. But naming things is very hard. I'd be happier if people just adopted a consistent naming scheme that is predictable. I'd put up with the crazy long names in exchange for that.
layer8 3y ago
What is clear depends on context, familiarity, and expectations. It’s not an objective measure when those vary (and they often do vary). In addition, some amount of redundancy is useful for guidance and to avoid misinterpretations. It’s more an art than a science.
deleted 3y ago
[deleted]
HumblyTossed 3y ago
Of all the things I have to do on a daily basis, naming things is nearly at the bottom of my give a shit list. If you named a particular thing "FRED", I wouldn't care. I can read the code and get the context. A bit extreme, but the point is that all of this is just a waste of time. A WASTE OF TIME. Name it close to what you think it is and move on with your life.
- yCombLinks 3y ago
  You're not just wrong, but completely wrong. I would rather have code with good names but a compile error checked in than code with bad names. Anyone can fix the compile error, but to fix the names they have to take the time to understand the entire problem domain.
  - HumblyTossed 3y ago
    > Name it close to what you think it is and move on with your life. This isn't wrong. Wrong is obsessing over something so stupid.
koinedad 3y ago
I definitely agree…the opposite of this takes a lot longer for me to read and understand. I think the point includes reducing unnecessarily complex terminology as well. Do we have to “execute” a function or can we just simply “run” it?
paxys 3y ago
In the age of IDEs I don't even care about the name. Call everything "function" and write a description right above it in comments that can be picked up in autocomplete. If not, I'm probably not bothering with your library.
esafak 3y ago
"Fresh fish sold here today" https://kathakids.com/folktales/fresh-fish-sold-here/ https://kathakids.com/folktales/fresh-fish-sold-here/
Clubber 3y ago
So let's take his example and reverse it. At first glance, what does this code do? fetcher = repolib.IndexFetcher(args.arch) counts = collections.Counter() for repo in fetcher.get_repos(): for file in repo.files: counts[file.name] += 1 for repo, count in counts.most_common(10): print(repo, count) Can't really tell, the names are too short. It's clear to him right now because he's intimate with the code. I'll bet it won't be clear to him in 6 months after he's crammed 100,000 lines of unrelated code into his brain. It certainly won't be clear to some poor sod with zero familiarity who has to come in behind him and maintain it. His basic premise is correct: Names should be as short as possible while still being clear. Unfortunately he didn't follow his own premise. Err on the side of too long but clear, because maintenance is 90-99% of the project's life cycle and reading code is at least 5x harder than writing it. You should name variables/methods as if you won't be touching it for 6 months and you want to be able to have a decent understanding of what it does within 5-10 seconds of reading it.
em500 3y ago
I think there are main reasons why computer code often have verbose names for functions and variables is that there is a great variance (1) in the application domain of code and (2) the knowledge and background of people who might read and work with your code, making it difficult to assume anything about them. Compare this with the condensed and cryptic music or math notation: they are very inaccessible to readers without many years of training. But that all training, that common understanding, is usually assumed of the reader.

85 points by benhoyt 3y ago

I'm not knocking the article, but endless aesthetic discussions like this are one of the reasons why I can't wait to leave the industry. The very definition of bike-shedding. compare acquire and take_ownership Who cares!? Those are both great names for a function... If you put 10 software engineers in a room, you'll get 10 different answers to any question. Every company you work for will be filled with endless "smart guys", ready to spring in to action and nitpick you to death about arbitrary things. It's exhausting. We need more languages that come with rigid rules for things like style, so we can stop wasting time and get on with solving problems.

kspacewalk2 3y ago
While I share your frustration, I think leaving the industry because of it is an overreaction. It's fairly easy to just ignore the aesthetic discussions and focus on solving problems. Whenever someone brings up renaming a function from perfectly_good_name_1 to perfectly_good_name_2 in code review, I immediately agree without discussion and move on with my life.
- spicyusername 3y ago
  Indeed, indeed. Maybe a more accurate phrasing would be, "Can't wait to retire and do literally anything else with my time, including writing programs with which I answer to no one about coding style.", Hah.
- 000ooo000 3y ago
  >It's fairly easy to just ignore the aesthetic discussions and focus on solving problems. You probably know this but for discussion's sake: in many modern forges, your pull request can't be merged unless the comments have been resolved/closed. So you basically cannot ignore these "feedback" items; you have to engage the comment whether that means actioning it or refuting it. I currently work with the worst pedant I've encountered in my career to date, and I can empathise with wanting to leave the industry.
  - Maxion 3y ago
    > I currently work with the worst pedant I've encountered in my career to date, and I can empathise with wanting to leave the industry. I have one of these too, one of my PRs received a comment on the third round of review about correcting a minor typo in a comment that was made years ago by someone else.
    - gwright 3y ago
      FWIW, we started using https://conventionalcomments.org https://conventionalcomments.org a while back and found it to be a useful tool for making it easy to communicate what is an issue that needs to be fixed, a suggestion to consider, or a nitpick to optionally ignore. It is still just a tool and does require the team to buy-in and utilize it, but we've found it helpful.
    - jrd259 3y ago
      If the comment was in code you touched, this seems right. Typos affect searchabilty. If the typo was outside (but close to) the block you modified you shouldn't be required, and the team ought to have rules of engagement to state this.
  - mannykannot 3y ago
    It would be better for all if the pedant left the industry, but they typically have too much self-worth invested in an inflated perception of their expertise within it.
  - SCdF 3y ago
    What is a forge in this context? Is that a name for a code repository website? I'm unfamiliar. Regardless, I think that's just a function of your team and your dynamics that you've built up. On the current team I'm on we for example don't require this (at least on GitHub its configurable), there is an understanding of nits, how to declare them and what that means, as well as an understanding of using request changes vs approve and so on. We've built this up by having discussions about what the purpose of reviews are (eg making sure your code is understandable by someone other than you), having a common understanding that perfect should never get in the way of good, etc. We regularly have retrospectives where, if we were having issues with really bad pedantry, I would hope it could be brought up.
Aardwolf 3y ago
Automatic style formatters solve a lot of this discussion. Not all, such as the naming example here, but at least things like whitespace and line wrapping never have to be a discussion point again if you have the rule that whatever the style formatter outputs is what you use
3cats-in-a-coat 3y ago
Bikeshedding is prevalent in every popular area of human study, because it's easy to talk and write about. It's not representative of what matters to those who get the job done.
- ozim 3y ago
  Bike shedding is not the problem here. Attitude is, if I can argue with someone and have it in a fun productive way - even if we don’t tackle most important thing we should work on at the moment - it still might be valuable. If I have to deal with smartass that nitpicks on variable names, he wastes my energy and any will to do further work for the day or if it is more heated and goes over some “Astro architecture” might even burn my willpower to do any work till the end of the week.
  - 3cats-in-a-coat 3y ago
    I don't mean to bikeshed, but you seem to be describing bikeshedding. Bikeshedding in practice is often accompanied with aggressive arguments because some (or both) sides just really want to be right about something, as a way to offset their real worry, despite neither choice solves their real problem. Although I guess it could also be a pleasant chat, why not. Consider for example the bikeshedding society did on whether to distance 1.5m or 2m during COVID, and how precisely and how long to wash their hands. We had a ton of those. When people feel out of control they want to own a decision that makes them feel like they're back in control. Programming is complex at scale. But bikeshedding about how many characters our lines, how many lines our functions, and how to name things is always there for us to argue about. Oh and whether a class is truly single responsibility, that's an evergreen.
    - jjk166 3y ago
      That's not bikeshedding. Bikeshedding is focusing on an unimportant but familiar aspect of a complex project specifically because one lacks the technical knowledge to discuss the important parts. Bikeshedding might involve nitpicking, but it doesn't have to, and one can nitpick without bikeshedding. Maybe a code reviewer is genuinely so inept they can't understand anything more complex than naming standards, but far more likely they're just a bit neurotic with regards to following standards.
000ooo000 3y ago
>nitpick you to death about arbitrary things Yep, it gets tedious. It really grates on me when reviewers are willing to die on a hill over some minutia while the codebase is in tatters. Arguing over extremely minor duplication while there exists two, active, physical copies of an application in separate repos (a real example) is the most pennywise poundfoolish waste of time and it drives me crazy.
- b112 3y ago
  I once spent 8 months merging a codebase with almost every single function duplicated three times, and all that was required for each (most of the time) was another parameter, one conditional in function, and all 3 could be merged. So I did that! And at the same time cleaned up the code, fixed bugs, and adding required new functionality, and all while merging in constant change from the main codebase. After reducing a 1M line codebase to 280k lines, when almost done, after that 8 months, I was asked "how much longer". My response of "a month for testing" was apparently too long for the new manager, who turfed all those fixes, including the new functionality. And I wasn't even behind schedule, I was ahead. Once abandoned, everyone just copy and pasted my changes... in triplicate, into the old codebase. Which took 3 months, instead of 1. Bah. A year of my life wasted.
  - glenjamin 3y ago
    This is a great cautionary tale about what happens if you don’t continuously integrate changes in an incremental fashion.
    - b112 3y ago
      It's a great cautionary tale of management dumbassery. (yes I am still bitter)
  - 6keZbCECT2uB 3y ago
    Spending 8 months when the business value at the end was mostly improved velocity doesn't sound likely to be a good tradeoff, especially if this is done as a big bang effort which either succeeds holistically or fails. You might have better success in the future by finding ways to integrate maintenance improvements incrementally.
diegoperini 3y ago
I wonder if there are linters that can check if a method/function name starts with a spell-checked English verb.
matwood 3y ago
I don't consider myself a great programmer, but I do think I do two things well. One is solve problems. Like a dog with a bone I become obsessive about figuring something out. The other is I don't care about style, and will happily fit the existing style. For me, it's consistency above all else. I agree completely with you that arguments around style are exhausting.
- JohnFen 3y ago
  > For me, it's consistency above all else. Entirely this. I have a preferred style when I'm writing my own code. When I'm writing code for someone else, though, I will roll with whatever the house style is[1]. I just want consistency and predictability. Once I know the naming scheme, I should be able to take a really good guess as to what any given function or variable name is by knowing what they do, and vice versa. [1] I consider it a red flag if a company doesn't have an established house style. It matters not what the style consists of, only that it exists and is mostly adhered to.
draw_down 3y ago
[dead]
zajio1am 3y ago
> Who cares!? Those are both great names for a function... The source code has two purposes - to be processed (compiled/interpreted) by software, and to be read by humans. While it is relatively clear what is considered good code for the first purpose, it is harder to say what it is for the second one. An essay could be written in an elegant style or be full of clumsy wordings and hard to understand sentences, despite having the same meaning. The same is true for source code.
bborud 3y ago
Naming things sensibly and doing so consistently is pretty important in designing software because names are relied on to convey meaning. Sensible naming helps people. Bad and inconsistent naming confuses people. Naming matters more for interface types and APIs than for local variables. "acquire" and "take_ownership" might be equally good names for an operation, but you should pick one and stick to it throughout the codebase. And it would make sense to poll other people about what they think is a good name. Especially if you don't really care one way or another. Other people may have valid perspectives or they may just be better at expressing meaning through names. You can't really nail everything down in the official style guide for a language without it becoming baroque and oppressive. If you want to avoid bikeshedding, have a process in place for choosing naming conventions. Name someone as the arbiter. If consensus cannot be reached within a reasonable amount of time, the arbiter decides. It might help to keep a record of naming choices so people understand the reasoning behind why certain practices are chosen. Most programming is a social activity in that multiple people will have to deal with the code. Not caring about something as essential as naming, and wanting to avoid effort because you don't care, can be seen as a kind of anti-social behavior. On well functioning teams I've worked on, naming tends to not be a big issue because over time a team develops a common vocabulary. When in doubt, ask someone else on the team how they interpret a name.
- coffeebeqn 3y ago
  I agree that consistency is what’s important. If almost everything in the codebase roughly follows the same API then it takes less effort for people to use the various parts
Kapura 3y ago
I agree that "Who cares!" should be the default response here, as long as it's clear, but I think some folks (especially in engineering) think that "more rules = more clear," or "if we encode all of this information in the variable name, the variable name will always be clear," which is an error in thinking this particular article seeks to correct. I have actually been in the throes of battle with co-workers over relaxing our variable naming standards because they are too damn prescriptive, which (in my opinion) reduces code clarity, while also setting up conflicts between those who think code should be as clear as possible in the file versus those who think that we should follow the standard even though we know it to be flawed and produce overly-verbose code. My core argument is very much "who cares as long as it's clear" but having a specific piece of ammo where I can say "here are several arguments specifically against our current style" may convince some of these folks to loosen up a little bit. The bike-shedding is indeed ridiculous; going back and forth in Swarm for days over names for code that has fundamental algorithmic flaws. Awful stuff.
drewcoo 3y ago
> If you put 10 software engineers in a room, you'll get 10 different answers to any question. Again with the hypothetical dichotomies!
- Joker_vD 3y ago
  In my experience, getting N software engineers in a room produces exactly N different answers only if you don't allow them to debate further. If you do, the upper bound on the number of different answers seems to be is at least 3N.
halfnormalform 3y ago
The latter is probably a better name if there are other functions involving "ownership" (give_ownership, split_ownership, etc.), but otherwise you're right.
- squirtlebonflow 3y ago
  Yep, I've seen situations where the programmer goes for brevity, and then runs into problems in the future when they want to "be consistent" take_ownership -> acquire (fine at first) give_ownership -> unacquire (not even a word) split_ownership -> halfacquire (complete nonsense) then there needs to be a way to split ownership other than an equal 2-way split and you're fucked. I haven't seen this exact situation, but I've seen stuff like this. And sometimes, I was the programmer. Names should be as short as possible while still being meaningful AND keeping in mind future work requirements. On a tangent, I'm always frustrated when as a developer, I don't learn much about the actual business. There's always a situation down the road where if you had known what the company was planning on doing in the next quarter, or couple years, you could have saved everyone some work by doing things differently.
  - cperciva 3y ago
    unacquire This reminds me of when some code was lightly edited to remove references to "master" and "slave", only to end up with a function "enminion".
Shrezzing 3y ago
[flagged]
chinchilla2020 3y ago
Yeah it is unfortunate. Ever dealt with a rotating code review that passes through multiple hands? It's funny watching the principal architect and technical fellow ask me to refactor my code again to remove the changes that the other one asked me to make! I spent a month in one such code review. No wonder management hates listening to engineers. If we have a good point to make, they ignore it because of the last 3 engineers who wasted time with stylistic, pedantic arguments.
ecshafer 3y ago
A particular gripe of mine is the tendency for some code reviewers to nitpick code golf solutions that don’t really improve clarity, maintainability, or quality (and might arguably reduce them). Going from 40 characters to 30 characters for a functionally equivalent statement isn’t a win worth mentioning in my book.
soligern 3y ago
I mean we have AI that generates both the function and an appropriate name for it. If you lean into that paradigm, all of this is a waste of time.
geodel 3y ago
It is more of software self-actualization. Just like human would need food, water, shelter, before they move on to top of pyramid. I agree software need to be basic error free, compilable, buildable and deployable before naming and structuring aesthetics becomes important. > Who cares!? Those are both great names for a function... Now the author has written many good quality working software systems, it is natural that they want to talk about next level things.
omoikane 3y ago
What we used to do is announce in our team chat: "anyone around for a round of bikeshedding? I need to name a thing". The thing being named is usually not user facing, so it was more of a team building exercise than anything related to compliance or style. We would get it done in a few minutes and never discuss this name again, because we already had this discussion. The actual names that came out of these exercises are generally pretty good, and often a shorter name would win over a longer one.
- JohnFen 3y ago
  > "anyone around for a round of bikeshedding? I need to name a thing" I have to come up with many names for things in code every day. I can't imagine the slowdown having to workshop every name would incur...
  - Shaanie 3y ago
    I'm sure the names have different importance, though. A local variable name in a small method probably barely matters, whereas the name of a variable in a widely used external API matters quite a lot.
  - omoikane 3y ago
    This is the kind of exercise can be done in the background while waiting for stuff to compile. It's also not for trivial things like private or local variables and such, so not really a frequently occurring speed bump. An example would be a set of enum names that I need to share with my teammates, where it might be a lot of hassle to replace them all if we don't decide on proper names now, but any set of names would work.
datavirtue 3y ago
Hmmm...no mention of business domain language. The main reason I want to leave the industry.
npsimons 3y ago
> We need more languages that come with rigid rules for things like style, so we can stop wasting time and get on with solving problems. This is where I'm at now. Decades ago, I was an "only spaces, no tabs" guy. Still am to an extent. But what made me more open was realizing it wasn't spaces or tabs specifically that mattered, only that code is readable, and consistently formatted code is more readable. Seeing things like `gofmt`, which mix tabs and spaces, and comes with the language? Your debate about spaces versus tabs is over, now we can get back to tackling real problems, and your code will be rejected at CI if it isn't run through the standard formatter. Same thing with `black` for Python. Above all else, be consistent. I can understand hate for "standard" language libraries that have functions with wildly different naming schemes or input and output arguments that aren't consistent - those should DIAF (looking at you, PHP "standard" library). But as to the names themselves? Doesn't particularly matter much. Unless you're the Bruce Tognazzini of API design, you probably don't have anything of substance to back up why it should be "make_" versus "create_".
- sdfghswe 3y ago
  > Above all else, be consistent. Aren't you still doing the same thing though? You have your arbitrary rules and they're absolutely truths... until you change your mind about them. Except before the rule was "only space no tabs" and now it's "be consistent"?
  - npsimons 3y ago
    Given how many people here are disagreeing except on "be consistent", I feel I'm in good company in having that as my rule. I'm not being inconsistent, I'm learning, growing and adapting. "Strong opinions, weakly held." But yes, "A foolish consistency is the hobgoblin of little minds." The question is, what is "foolish"? I'm arguing against things like `strpos` and `str_rot13`. I'm arguing against having similar functions where argument order is inconsistent. These are the sorts of things that slow developers down and force them to check the documentation every time just to make sure they aren't introducing bugs by default.
    - 3y ago
benhoyt 3y ago
Not surprisingly (as the OP), I disagree. Good names help people understand concepts; bad names confuse. Choosing good names is not merely aesthetics, it's bringing clarity, meaning, and culture. That said, in this particular case, I think Russ could have chosen a better example. Neither "acquire" nor "take_ownership" are terrible. But when you're a language designer (like Russ), the names you choose shape people's code and their thinking for the next 10, 20, even 50 years. When you're a library designer (many of us are), it might only be a few years, but still. I think as code reviewers we should take this as seriously as the context demands: for internal names and local variables, it's not too important. For public API names, very important. For language changes, extremely important. Some good quotes from Bob Nystrom, author of "Crafting Interpreters": "Names are the structure we impose on the formless sea of bits that is computing." http://journal.stuffwithstuff.com/2016/06/16/long-names-are-long/ http://journal.stuffwithstuff.com/2016/06/16/long-names-are-... "For me, thinking about names is inseparable from the process of design. To name something is to define it." http://journal.stuffwithstuff.com/2009/06/05/naming-things-in-code/ http://journal.stuffwithstuff.com/2009/06/05/naming-things-i...
- spicyusername 3y ago
  I don't disagree that things like function naming are important. I understand that it's important to think critically about the philosophical North stars of your work. This is precisely what it means to be an "expert". I appreciate the work you're doing adding your voice to the discussion. That being said, it doesn't change the fact that, for me, it's tiring working in a profession where nothing is "real". There is never going to be an end to these kinds of discussions, because everything is abstract, relative, and ever-changing. Unlike many other professions grounded in the limitations of physical reality: carpentry, civil engineering, hair cutting, etc, Software Engineering is a house of cards of artificial abstractions. The tools and architectural patterns are mostly free from physical constraint, so they can change at will, and they do. What is "good" is highly dependent on context, and in our case that context is fluid, changing along every dimension all the time, making it very hard to establish a shared understanding of any given problem. This translates into a work culture where there is always room for debate about what to do, since there is almost never an objective best next step. And debate we do.
toss1 3y ago
>>Who cares!? Serious devs care. I was once at a software conference where Bjarne Stroustrup was givnig some presentations, and in the after-session questions, I thought I'd ask about something that had been bugging me about software design in general — I'd found myself spending what I thought might be excessive time to designing naming systems for the projects I worked on, and I wondered what he thought about spending time on naming conventions. With no hesitation, he said "Not at all, naming is very important", and very useful to get right up front, even for solo projects, as good clear naming helps speed the entire building and maintenance. So, yes, both "acquire" and "take_ownership" are relatively synonymous, but one will clearly be better and more consistent with the other in the context of your naming system. And this will matter to at least some serious devs. (But YMMV; if you have tried it a couple times and found it doesn't help you a bit, then you probably shouldn't spend more time on it)
Pannoniae 3y ago
"We need more languages that come with rigid rules for things like style, so we can stop wasting time and get on with solving problems." I have the complete opposite opinion. Most software engineers are obsessed with style, and I don't think accommodating it is the right solution. I think the right idea is just not enforcing any stylistic rules at all (while obviously keeping the readability and maintainability-related rules) and just let everyone write code how they want, while forcing them to tolerate other people's coding, naming, brace placement, etc. styles.

ape4 3y ago

Since fetching webpages is very common we know `send_get_request_and_receive_response(url)` is wordy. Of course you need to get the response. But in some other area it might be obvious so naming the function with more words could be useful.

cwbrandsma 3y ago

There are only two hard problems in computer science: naming things, cache invalidation, and off by one errors.

ozim 3y ago
I think one problem with first problem is that names are not going to live forever just as the code. Lots of times code will be scrapped, a lot of times code will just run and no one will ever mind changing it. So I’d say amount of time invested in naming won’t payback.
- erik_seaberg 3y ago
  It’s very hard to change stuff that has grown beyond your control. Local variable names? Sure. API names? That’s a major version break. Correcting the “Referer” header? Unthinkable for 27 years and counting.
hinkley 3y ago
After you fix a few cache invalidation bugs, you realize those problems are mostly about identity, and identity is just another form of naming things.
proto_lambda 3y ago
There are only two problems in computer science: we only have one joke, and it's gotten old.
- bcrosby95 3y ago
  There are 10 problems in computer science: we only have two jokes, and one of them is bad.
  - zhte415 3y ago
    What about the other 14?
  - 3y ago

boringuser2 3y ago

Using Golang as an example of naming conventions is questionable - this is a language where single letter variable names are idiomatic. I feel like the author missed the obvious; a name should reduce cognitive load as much as possible. Length is one factor that is relevant to this goal, but not the only factor. When a name is too long, this is usually a design issue, not a stylistic issue, i.e. writing Swiss Army functions. Also, takeOwnership is not inferior to acquire, it's just about a wash.

hinkley 3y ago
You can lead a developer to cognitive theory but you can’t make him think.

hahn-kev 3y ago

Just define clear. Clear to you? Or me?

jacknews 3y ago

Is this news? Who said naming was difficult? Obviously all you need to do is make names as short as possible, but no shorter! Simple!

jncfhnb 3y ago
You got it, j3!

natch 3y ago

>”… Make every name tell.” >That last sentence is poetry. It’s a borrowing from Strunk & White, “make every word tell.”

mpolichette 3y ago

I tend to agree, however, I typically tell people that if you see longer function names, you should watch out for complexity. In fact, if I have to write some overly complex code that I can’t isolate for some reason, I will usually try to show it in the names being extra long.

JorgeGT 3y ago

The "clear" part is often the issue. My favorite example: - In Mathematica, if you want to plot a vector field, you use VectorPlot[] - In MATLAB, you use... quiver(). You know, because it holds a lot of arrows. Short and clear, eh?

njovin 3y ago
"Clear over Clever" is a pretty simple rule that helps avoid this type of thing.
appleflaxen 3y ago
Super clever. Very unclear to anyone who is new to that functionality, though.
dredmorbius 3y ago
There's a possible higher-order argument for `quiver()`: the name is idiosyncratic, and sufficiently enough that it might tend to get remembered, which is useful for however many more minutes humans are actually writing code in this world. As contrasted with "VectorPlot": was that "VectorPlot", "VectorGraph", "TensorPlot", or "PlotVector"? "quiver" is short and sweet and slightly unusual but also conceptually related in a sense to the function. I'm not saying that "quiver" is the better name, though I'm offering some arguments as to why it might be.
npsimons 3y ago
> - In MATLAB, you use... quiver(). You know, because it holds a lot of arrows. Short and clear, eh? "Shaka, when the walls fell." Sure it's poetic, but WTF do you mean?

TheDesolate0 3y ago

[dead]

jlund-molfese 3y ago

Properly communicating when a requested change is optional is actually one of the most important code review skills you can have. By default, developers assume that a requested change is mandatory. So as a reviewer, it's up to you to explain the difference between a change you're suggesting because it's more concise to use a list comprehension instead of a loop vs a change you're requiring because the change list introduces a race condition that will cause customers to lose money. If you do that, you'll make everyone you work with happier

rsyring 3y ago
We prefix any comment or request with "nit", as in "nitpick" when the reviewer knows they are being picky but it's still something worth mentioning. The coder in that case knows they can ignore that without consequence if their preference or perspective is different. The reviewer also knows that and doesn't feel bad if that advice is ignored. It's been helpful for me because I'm a picky reviewer and feel compelled to mention things that my years of experience tell me are "wrong." But I've also come to realize it's often not wrong, just not as good for potentially non-obvious reasons. But my devs will never learn the potentially "better" way if I don't point it out. So "nit" gives me a way to communicate and teach without the pressure of the dev needing to make an immediate change.
- jlund-molfese 3y ago
  Same! I also, if I notice I'm leaving a lot of constructive comments, deliberately try to leave some positives ones too. Like "Nice! Glad we're adding typing here". Just as important to promote positive habits as discouraging negative ones.

hinkley 3y ago

Every code base where naming still matters is a code base that is sprouting new functions. What was “clear” two years ago may be unclear today because we have four times as many functions. Via the pigeonhole principle, there are no short names that are sufficiently clear, and as X goes to infinity even the medium ones become problematic. Use a modern IDE with autocomplete. Try to make the beginning of your names as unique as possible. Few people will have to type in the suffixes. Used to be we would ask other developers what book they would buy all of their coworkers. Answers have changed over time, anything from Brooks to Gamma. But for my money, I would buy them a thesaurus. If you use the same word in two places in the code, they should be sharing code and data structures. If they don’t, you should use a synonym. Never recycle names, and be sure you aren’t recycling. Many people are wrong here, claiming two things are the same but with no code shared, and in many cases I’ve seen, using two different definitions of the same word.

deleted 3y ago
[deleted]

natch 3y ago

The hard part of naming is none of these things. The hard part is dealing sensitively with snowflakes who think naming doesn’t matter and instead of saying this to your face, they privately have conniptions trash talking you behind your back when a minor improvement is suggested. They’ve made it so that naming cannot be discussed. If you see a horrendous name and suggest an improvement, there’s no overt response, but later you hear from your friend that the poor namer is accusing you of wanting to die on a hill. Dude. It was just a suggestion. And it was labeled as a nit. You don’t have to take it, even though we’d be better off if you did. So I’ve all but abandoned ever suggesting improved names, unfortunately. Being a good team player is more important. I name my stuff well, but what others do is up to them.

throwawaaarrgh 3y ago

Naming things should be as short as possible while still being clear, unless the context of the situation makes a longer name solve some other problem. Naming things should be short as possible while still being clear, unless making it longer helps something else. Name things short as possible while still clear, unless longer helps something else. Name short as possible while clear, unless longer is better. Name short and clear, unless longer better. If longer not better, name short & clear. if_longer_not_better_name_short_clear ifLongerNotBetterNameShortClear

6keZbCECT2uB 3y ago

This comes into tension with making names as clear as possible while still being short. Frankly, I don't find coming up with short names for things to be easy, let alone good names even when taken to the extreme. Whether something is too short depends on your context. requests.get might be ambiguous for someone who has never seen the code base before, but will quickly get obviously with a little exposure, so does the code base have dedicated maintainers? The skill of good naming isn't distributed evenly and OP's names are pretty good, so I'd be happy for them to come along to my code base and rename things as long as it was within other constraints (not consuming too much time, doesn't break api, etc).

stronglikedan 3y ago

Well, of course. This could also be said as "use long names when short names can't be clear enough." Don't be afraid of long names since we have modern IDEs with competent auto-complete. Also, long names go a long way when searching a codebase.

crazygringo 3y ago

> However, I think the more common mistake is using names that are overly long. But the most productivity-sapping mistake is names that are too vague. The idea that "names should be as short as possible while still being clear" is a truism I don't think anyone disagrees with. But it's a balance that nobody ever perfectly gets right. So if you're going to err, it's better to err on the side of clarity rather than shortness. E.g. lines like: fetcher = repolib.IndexFetcher(args.arch) counts = collections.Counter() for file in repo.files: Would be better as: repo_fetcher = repolib.IndexFetcher(args.arch) file_counts = collections.Counter() for repo_file in repo.files: It's far more helpful when a line of code tells you what it's doing not just in terms of programming logic but in terms of the purpose of the code, the contextual nouns and verbs. It saves a lot of mental effort when reading and debugging.

contravariant 3y ago
If we're debating style anyway I'd argue using agent nouns as a class name is a worse offence. Compare index = RepositoryIndex(args.architecture) statistics = RepositoryStatistics() for repository in index.retrieve_repositories(): for repository_file in repository.files: statistics.increment_file_count(repository_file.name) This is still mostly equivalent to the original, but a lot easier to read and pretty much every word removed from the name can be inferred from the type. It can be made even less verbose but at this point there's no real need.
- jimmaswell 3y ago
  No one was ever hurt by a noun in a variable. Longer and more descriptive is fine.
classified 3y ago
There are two hard things in software development: Cache ivalidation, naming things, and off-by-one errors.

bborud 3y ago

Another place where naming matters, but for slightly different reasons, is on the command line. If you are naming a program that someone is going to spend much of their time running from the command line, it is nice if you put some thought into how the binary is named. For instance. I've never been able to understand why something like `systemctl` could be so clumsily named. If you have to do sysadmin work, sometimes you will be using the command a lot. If we ignore the fact that I see more and more people typing out entire commands without the use of completion, `systemctl` lacks a short, unique prefix and ends up being quite awkward to type. On my system `sys` is the prefix for 26 commands, and `system` is the prefix for 24 commands. So I end up having to type 7 keystrokes to type systemctl on my system with completion. Sure, I could alias it, but then I'd have to replicate it everywhere, plus I'd be forming habits that just cause more frustration later. Another way to fail is to choose a prefix that has bad typing flow. For instance I wrote a program that has the prefix "aq". Try to type it. Awkward, isn't it? (If you don't think any of this matters, perhaps you shouldn't be the one to pick names for programs that are run on the command line).

jjk166 3y ago

IDE space is free. Copy and pasting a long string takes no more time or effort than a short string. What you stand to gain from shortening a name is trivially small compared to the risk of making a name too short, potentially leading many people to each waste time trying to figure out what you meant. The author's real problem is not about an excess of characters, it's that names are often long because they include redundant or irrelevant information. Still an incredibly minor issue, but there's some legitimacy to that. Better advice would be to keep names informative.

thfuran 3y ago
But the visual field is finite and filling it with fluff doesn't help anyone.
- jjk166 3y ago
  Your field of view can be moved to sweep over an infinite area. Again, including fluff might not help but it's infinitely preferable to not including something important.

mcpackieh 3y ago

Sure, brevity is the soul of wit and all that. Just so long as you don't go dropping letters from the middle of words because you're going for the unixy aesthetic. That style is an anachronism from an era when symbol length was limited, it doesn't belong in modern code.

fastball 3y ago

My top priority when naming things is discriminated grep-ability: if/when I want to refactor my code and find all occurrences of a certain function call, will this name allow me to do it in a way that is distinct from other names? After that I mostly agree with the author that short and clear are the next two priorities.

lolsal 3y ago
I have found myself thinking about this as well the more my career matures. It’s a great thing to consider.

asimpletune 3y ago

Swift is one of the only languages that actually makes long names work. Rust's flavor of variable shadowing is a great way to support developers to keep names short.

JoeAltmaier 3y ago

What goes around comes around. We had naming conventions that produced succinct names. They became denigrated and shunned (for no good reason) - use long descriptive names! Now we see that was a bad idea - longer names just allow for more wasted words and are actually less descriptive. Some kind of social or algorithmic convention makes them quicker to parse and understand. I suppose some compromise will be proposed one day. Maybe a prefix to classify the method name, then some short description. Or even an IDE convention to pop up a short description for method names to allow clarification in-situ.

javier_e06 3y ago

Ed, says the variable name is too long. Sebastian says is too short. Waldo is not sure. A variable name should be easily inspected across the whole project using grep from the root directory of the project.

JohnFen 3y ago

> Some developers do use names that are too short. However, I think the more common mistake is using names that are overly long. I agree 100% with this. Overly long names are very painful to work with. But naming things is very hard. I'd be happier if people just adopted a consistent naming scheme that is predictable. I'd put up with the crazy long names in exchange for that.

layer8 3y ago

What is clear depends on context, familiarity, and expectations. It’s not an objective measure when those vary (and they often do vary). In addition, some amount of redundancy is useful for guidance and to avoid misinterpretations. It’s more an art than a science.

deleted 3y ago

[deleted]

HumblyTossed 3y ago

Of all the things I have to do on a daily basis, naming things is nearly at the bottom of my give a shit list. If you named a particular thing "FRED", I wouldn't care. I can read the code and get the context. A bit extreme, but the point is that all of this is just a waste of time. A WASTE OF TIME. Name it close to what you think it is and move on with your life.

yCombLinks 3y ago
You're not just wrong, but completely wrong. I would rather have code with good names but a compile error checked in than code with bad names. Anyone can fix the compile error, but to fix the names they have to take the time to understand the entire problem domain.
- HumblyTossed 3y ago
  > Name it close to what you think it is and move on with your life. This isn't wrong. Wrong is obsessing over something so stupid.

koinedad 3y ago

I definitely agree…the opposite of this takes a lot longer for me to read and understand. I think the point includes reducing unnecessarily complex terminology as well. Do we have to “execute” a function or can we just simply “run” it?

paxys 3y ago

In the age of IDEs I don't even care about the name. Call everything "function" and write a description right above it in comments that can be picked up in autocomplete. If not, I'm probably not bothering with your library.

esafak 3y ago

"Fresh fish sold here today" https://kathakids.com/folktales/fresh-fish-sold-here/ https://kathakids.com/folktales/fresh-fish-sold-here/

Clubber 3y ago

So let's take his example and reverse it. At first glance, what does this code do? fetcher = repolib.IndexFetcher(args.arch) counts = collections.Counter() for repo in fetcher.get_repos(): for file in repo.files: counts[file.name] += 1 for repo, count in counts.most_common(10): print(repo, count) Can't really tell, the names are too short. It's clear to him right now because he's intimate with the code. I'll bet it won't be clear to him in 6 months after he's crammed 100,000 lines of unrelated code into his brain. It certainly won't be clear to some poor sod with zero familiarity who has to come in behind him and maintain it. His basic premise is correct: Names should be as short as possible while still being clear. Unfortunately he didn't follow his own premise. Err on the side of too long but clear, because maintenance is 90-99% of the project's life cycle and reading code is at least 5x harder than writing it. You should name variables/methods as if you won't be touching it for 6 months and you want to be able to have a decent understanding of what it does within 5-10 seconds of reading it.

em500 3y ago

I think there are main reasons why computer code often have verbose names for functions and variables is that there is a great variance (1) in the application domain of code and (2) the knowledge and background of people who might read and work with your code, making it difficult to assume anything about them. Compare this with the condensed and cryptic music or math notation: they are very inaccessible to readers without many years of training. But that all training, that common understanding, is usually assumed of the reader.