[HN Gopher] Names should be as short as possible while still bei...
___________________________________________________________________
Names should be as short as possible while still being clear
Author : benhoyt
Score : 74 points
Date : 2023-07-03 09:02 UTC (14 hours ago)
(HTM) web link (benhoyt.com)
(TXT) w3m dump (benhoyt.com)
| JorgeGT wrote:
| 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 wrote:
| "Clear over Clever" is a pretty simple rule that helps avoid
| this type of thing.
| dredmorbius wrote:
| 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.
| appleflaxen wrote:
| Super clever.
|
| Very unclear to anyone who is new to that functionality,
| though.
| npsimons wrote:
| > - 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_?
| spicyusername wrote:
| 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.
| halfnormalform wrote:
| 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 wrote:
| 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 wrote:
| _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".
| geodel wrote:
| 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.
| 3cats-in-a-coat wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| 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.
| omoikane wrote:
| 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 wrote:
| > "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...
| omoikane wrote:
| 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.
| bborud wrote:
| 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 wrote:
| 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
| npsimons wrote:
| > 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 wrote:
| > 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 wrote:
| 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.
| sdfghswe wrote:
| > I feel I'm in good company in having that as my rule
|
| I'm sure you also felt in good company about tabs or not
| tabs or whatever it was you liked.
| npsimons wrote:
| Kindly cite a problem with admitting mistakes and growing
| and learning from them.
|
| Then explain how consistency is a bad thing.
| sdfghswe wrote:
| > Kindly cite a problem with admitting mistakes and
| growing and learning from them.
|
| Nothing against this.
|
| > Then explain how consistency is a bad thing.
|
| This is a really boring conversation, because if I give a
| good example you'll just define consistency for that
| example not to apply. For example, picking the token case
| of naming functions in such and such way, it occurs to me
| that I don't really care if you break rules are long it's
| done in a way that doesn't affect the interface. If
| something can be considered an implementation detail, I
| don't care that it doesn't follow the same rules, as long
| as the interface doesn't allow you to see it. But then
| you'll just say something like "oh but 'consistency'
| doesn't mean a rule applies under any and all
| circumstances, there's always caveats" bla bla bla.
|
| It's a boring conversation, my point is that you had a
| dogma, and now you have a different dogma. You think
| you're evolving, I think you're changing but not evolving
| in a bigger way.
| diegoperini wrote:
| I wonder if there are linters that can check if a
| method/function name starts with a spell-checked English verb.
| draw_down wrote:
| [dead]
| benhoyt wrote:
| 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-...
|
| "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-i...
| kspacewalk2 wrote:
| 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 wrote:
| 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 wrote:
| >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.
| SCdF wrote:
| 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.
| 000ooo000 wrote:
| Yep you got it. Forge, aka GitHub, GitLab, Bitbucket, etc
| snovv_crash wrote:
| SourceForge being the prime example.
| yCombLinks wrote:
| I advise asking him to stop, and when he doesn't leave 75+
| comments on any PR he has.
| kspacewalk2 wrote:
| These kinds of silly games become tedious when you're
| trying to get something done, not to mention potentially
| damaging to your reputation given that the audience is
| your colleagues.
| bbarnett wrote:
| Wikipedia editing methodology transfered to code edits,
| hilarious.
| squirtlebonflow wrote:
| I'd like to work for a team where if you have ab aesthetic
| suggestion like this, you're only allowed to leave a
| comment if you also submit a commit.
|
| So the "actioning" part becomes their work.
| Maxion wrote:
| > 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 wrote:
| FWIW, we started using 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 wrote:
| 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 wrote:
| 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.
| Kapura wrote:
| 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.
| datavirtue wrote:
| Hmmm...no mention of business domain language. The main reason
| I want to leave the industry.
| zajio1am wrote:
| > 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.
| ecshafer wrote:
| 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.
| drewcoo wrote:
| > 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 wrote:
| 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.
| soligern wrote:
| 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.
| toss1 wrote:
| >>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)
| Shrezzing wrote:
| [flagged]
| Aardwolf wrote:
| 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
| chinchilla2020 wrote:
| 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.
| matwood wrote:
| 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 wrote:
| > 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.
| 000ooo000 wrote:
| >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.
| bbarnett wrote:
| 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 wrote:
| This is a great cautionary tale about what happens if you
| don't continuously integrate changes in an incremental
| fashion.
| bbarnett wrote:
| It's a great cautionary tale of management dumbassery.
| (yes I am still bitter)
| 6keZbCECT2uB wrote:
| 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.
| ASalazarMX wrote:
| This kind of refactoring also greatly improves robustness
| and stability, very worthy if the company values those
| qualities in their product.
| lcnPylGDnU4H9OF wrote:
| > finding ways to integrate maintenance improvements
| incrementally
|
| To be fair, it's possible bureaucratic process got in the
| way. If their commit / deployment process didn't allow
| for any changes to hit the production branch until it was
| "finished" then there wasn't really an opportunity for
| them to increment.
|
| That seems likely considering "the new manager, who
| turfed all those fixes, including the new functionality"
| suggests other organizational problems. If one month is
| too long for the new manager, the new manager's goal
| seems to be to "do things" rather than to "solve
| problems".
| efxhoy wrote:
| Did you maintain a separate branch for 8 months?
| bbarnett wrote:
| Yes, and merged in all edits.
|
| Others are discussing incremental changes, that doesn't
| work well when underlying frameworks have significant
| breaking changes.
|
| No everyone, I didn't choose the framework. No, I
| couldn't change it. No, I didn't choose the path.
|
| While I know people are trying to help, suggestions
| starting with "you should have" aren't very helpful here.
| asimpletune wrote:
| > suggestions starting with "you should have" aren't very
| helpful here
|
| But they might be helpful to others.
|
| There are ways to do these large refactorings that allow
| for incremental changes, never checking in a commit that
| breaks the build and where tests are passing at each
| stage. Your experience doesn't sound great and I'm sorry
| that happened to you, but I just wanted to add this to
| say that it's not necessarily personal.
| doorhammer wrote:
| I appreciate what you're saying here, and that your
| comment is more tactful than others, but I also see why
| the the op would be frustrated with the responses.
|
| The responses to far, to my subjective reading, imply
| that the OP did something stupid and that's why they were
| in that situation. Again, it's just a personal
| interpretation, but I don't think it's a far-fetched one,
| and I don't think we have the context to make that
| assumption.
|
| I agree that it can be useful to highlight the possible
| pitfalls to readers, but it's my opinion that it could be
| done in a more empathetic and tactful way that highlights
| our collective lack of context while still providing
| general advice to readers. I also think it would tend to
| lead to a more nuanced and useful conversation for the
| same readers.
| asimpletune wrote:
| Yeah, I agree completely. Thanks for taking the time to
| share your thoughts and to contribute to this community,
| that we all hold so dear, with a soft touch.
| justsomehnguy wrote:
| Just another time where prepending your words with 'IMO'
| would help much.
| npsimons wrote:
| As someone who gets mired in details, I can understand how it
| happens. It's _so_ much easier to focus on something you can
| control and fix.
|
| Not excusing or defending it, just trying to serve up a
| reason why it happens.
| esafak wrote:
| "Fresh fish sold here today"
|
| https://kathakids.com/folktales/fresh-fish-sold-here/
| JohnFen wrote:
| > 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.
| hahn-kev wrote:
| Just define clear. Clear to you? Or me?
| jlund-molfese wrote:
| 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 wrote:
| 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 wrote:
| 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.
| crazygringo wrote:
| > _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 wrote:
| 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 wrote:
| No one was ever hurt by a noun in a variable. Longer and more
| descriptive is fine.
| paxys wrote:
| 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.
| [deleted]
| TheDesolate0 wrote:
| [dead]
| HumblyTossed wrote:
| 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 wrote:
| 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.
| ape4 wrote:
| 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.
| jacknews wrote:
| 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 wrote:
| You got it, j3!
| hinkley wrote:
| 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]
| layer8 wrote:
| 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.
| natch wrote:
| 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 wrote:
| 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
| mcpackieh wrote:
| 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.
| natch wrote:
| >"... Make every name tell."
|
| >That last sentence is poetry.
|
| It's a borrowing from Strunk & White, "make every word tell."
| javier_e06 wrote:
| 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.
| JoeAltmaier wrote:
| 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.
| bborud wrote:
| 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).
| asimpletune wrote:
| 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.
| fastball wrote:
| 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 wrote:
| I have found myself thinking about this as well the more my
| career matures. It's a great thing to consider.
| mpolichette wrote:
| 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.
| cwbrandsma wrote:
| There are only two hard problems in computer science: naming
| things, cache invalidation, and off by one errors.
| proto_lambda wrote:
| There are only two problems in computer science: we only have
| one joke, and it's gotten old.
| bcrosby95 wrote:
| There are 10 problems in computer science: we only have two
| jokes, and one of them is bad.
| zhte415 wrote:
| What about the other 14?
| rufus_foreman wrote:
| I don't like computer science jokes. Not one bit.
| DonHopkins wrote:
| Oh no, you're off by one again! There's an even older one:
|
| Q: Why can't programmers tell Christmas for Halloween?
|
| A: Because OCT 31 = DEC 25.
| ozim wrote:
| 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.
| hinkley wrote:
| 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.
| jjk166 wrote:
| 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 wrote:
| But the visual field is finite and filling it with fluff
| doesn't help anyone.
| jjk166 wrote:
| 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.
| 6keZbCECT2uB wrote:
| 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).
| koinedad wrote:
| 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?
| boringuser2 wrote:
| 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 wrote:
| You can lead a developer to cognitive theory but you can't make
| him think.
| stronglikedan wrote:
| 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.
___________________________________________________________________
(page generated 2023-07-03 23:02 UTC)