Bikeshedding Names Considered Harmfull

The API design guidelines from which the principles of 'fluency' come were discussed quite thoroughly by this community more than two years ago and are, for better or worse, the rules which must guide the naming of Swift APIs. You are free to consider them 'misguided'; you are free to advance a proposal to replace them with something you find better, but simply pretending they don't exist isn't a viable option.

9 Likes

swiftEvolution.reduceQuantitativeAmountOfAsynchronousOnlineForumBasedBikesheddingWithRespectToPublicallyAvailableStandardLibrarySymbolNames()

5 Likes

All I’m saying is that the long compound-words names striving for grammatical correctness are misinterpretation of what fluency means in the context of programming languages. Swift is not Apple Script.

From the link:

Prefer method and function names that make use sites form grammatical English phrases.

Clarity is more important than brevity.

Include all the words needed to avoid ambiguity for a person reading code where the name is used.

Again, either naming follows the guidelines, or the guidelines must be changed. Whether the use of the word "fluent" in that document in its given context is correct or not is, to me, frankly irrelevant.

3 Likes

You seem to misunderstand me: I’m not arguing against the guidelines. I fully support them. Fluency as described in the guidelines is good. I argue against “fluency” used as a justification for bikeshedding. As in bickering over adding “is” here, “are” there, suggesting method names that repeat type information... these invalid arguments are super common during all bikeshedding sessions and is what prompts the referees to whip out the Guidelines and whack all the moles with them. We have a cultural problem. Count how many times @xwu cites guideline and calls for people to justify themselves in terms of the rules described therein. That would be a high signal-to-noise discussion I would love to see on SE. That is not what we have at the moment.

I’m saying bikeshedding is a tax on SE with a real cost that prevents much more important work.

Maybe because it is written a bit lower in the guidelines, people need to be reminded of this part more often:

Use Terminology Well

...

  • Embrace precedent. Don’t optimize terms for the total beginner at the expense of conformance to existing culture.
3 Likes

Maybe I’m misunderstanding you, but I don’t think that person’s first impressions of a codebase she’s unfamiliar with are that relevant. She needs to put in some work: look at the types, hover over unfamiliar functions to skim over the documentation. It has to make sense in this context. Requiring any and all code to conform to your first intuition is unreasonable. Catering towards willfully ignorant is a fool’s errand and when designing language API, I’d argue, unethical.

I think this is very true and well put, and I'm repeating it here unsure of whether it will increase or decrease the signal to noise ratio of this thread : ).

1 Like

Following recent PRs triggered this thread:

Also the Core team seems to be searching for systematic fix for bikeshedding:

So, this is a shameless ping for exposure. :sunglasses:

There was more to be said:

I’m not sure there aren’t more :man_shrugging:, until a proper response to this get’s me back to coding:

I guess I don't understand why you consider the discussion of names any more useless or tiresome than the discussion of any other aspect, e.g. whether to restrict a protocol to classes only, or whether Hashable should be a struct or a protocol. But to address your specific proposal in the original post:

  • Confining certain types of discussion to pitch phase only is a non-starter in my opinion. People don't have unlimited time, and many may only contribute to proposal discussions.
  • Encouraging people to “stick to their guns” can only harm the building of consensus, and changing your mind is a positive thing, not a negative thing.
  • The core team have restarted providing feedback during a pitch lately, so hopefully they can step in sometimes and break deadlocked discussions. As you mention though, sometimes they ask for feedback about names which I guess is only negative from your naming-averse perspective.

Edit: Did you somehow start three separate threads about essentially exactly the same issue? If you're looking for people wasting everyone's time, perhaps find a mirror.

13 Likes

Touché.

I thought I made my point more succinctly on second try and wanted to keep the related but different issues separate, for shorter read and to allow for pointed critique, without crossing the streams between them.

I even have a third one:

Am I in breach of some etiquette here? Should I ask moderators to merge those three posts into to this thread?

I also agree with you that my suggestions in the original post are not that great. From your response, I’m apparently not communicating clear enough, coming across as averse to naming discussions per-se. I take issue with bikeshedding, especially when it devolves into grammar fight. I’d like to find some way to systematically prevent that. Don’t you see that as an issue worth improving upon?

I think I have worked my way towards a simpler suggestion for curbing the bikeshedding in

How about a minimal tweak to the guidelines like this:

@forum_admins, could you please review if my 4 solo posts (tagged culture) are deemed excessive and if so, merge them into this thread in order of creation? :pray::heart:

I don't think Discourse lets us merge threads. I'm going to just lock the other threads and link them to here. If you want to repost their content in this thread, you can do that.

But yes, in general, please do not create multiple threads for discussing essentially the same point like that.

6 Likes

Apparently I can merge threads, but since there are four other threads I'd need to merge in, in the interests of not making a huge wall of text, I'll let Pavol decide what he wants to repeat here.

I would like to apologize for spamming you all with separate posts. I now also realize that their tone is quite overbearing and condescending for which I’m also truly sorry. I promise to do better next time.

On reflection, it all boils down to these points:

  • I suggest we avoid using the verb bikeshed when we mean “find a better name”.
  • Refocus the search for good naming on fluent interface instead of English grammar.
  • Prefer naming based on prior art, unless the novel name significantly clarifies the concept.
  • In discussions always evaluate naming in full context, including type information and documentation.
9 Likes

I think you're really on something, here. Proposals give a rational for proposed changes, and often describe the API changes, and that's great. But they very rarely contain any end-user documentation.

But documentation is a great tool: it helps polishing an API, testing its inner consistency and fitting with actual use cases, and even building up the culture around the proposed change.

When I say "culture" above, I mean culture in the Swift users community, not culture in this forum. This is important, because community culture is the only level in which APIs like map, flatMap, compactMap, formUnion, sequentiallyEquals etc. can live and coexist.

Now of course, documentation is better written by people whose job is to write documentation: it would be a bad idea to require a proposal to contain documentation of the highest quality, ready to be published as is. But a "Documentation Draft" chapter, written with Swift users in mind, not Swift Evolution readers or the core team, would be a much welcome addition.

This "Documentation Draft" chapter would be written as a Guide: a coherent piece of text and eventual sample code, with a beginning and an end, that introduces the changes and new APIs to a Swift user. A catalog of inline reference documentation of each new or modified method is not what I have in mind.

2 Likes

One has to ask at what point does review happen? An evolution to the language roughly involves these steps:

  • Discover and identify a problem
  • Research prior discussions and existing art in the Swift community
  • Motivate the problem with real-world contexts
  • Design a preliminary solution
  • Prototype a solution, iterating with previous step, ensuring implementability
  • Formalize the design
  • Name things well
  • Design code documentation markup (if that was not already done in prototyping)
  • Design and implement tests
  • Finalize a written proposal
  • Prepare a full pull request including clean code, in-line documentation, etc for apple/swift
  • Prepare a proposal pull request for apple/evolution
  • Proceed through review, possibly through revision

What I've left out of these steps is community involvement. With limited time, many people feel most comfortable focusing on review. Even a good pitch, such as one with broad support in comparable modern languages, may get almost no feedback. I'm thinking particularly about @johnno1962's recent raw strings work, which will probably die before revision due to the re-pitch requirement from the core team feedback.

It's then primarily during review that the design, naming, and motivation feedback (and iteration) starts to take place because it's only then that the proposal reaches sufficient eyeballs where for a brief period of time, it gains attention for the vast majority of the Swift community who participate even slightly in the SE process. All styles of feedback are valuable components. They are, generally, most available in the official review threads, where it can be headbangingly frustrating that insights were not previously available to drive the design, etc.

We have no comparable non-binding "design review" process that promotes an idea so that it gets the proper attention before proceeding further. There's no way to officially draw attention to a proposal early in the process other than putting up a "Pitch" or "RFD" post and hoping people will notice.

Compared the larger Swift community, SE is small. Compared to review thread traffic, pitch/rfd feedback can be sparse.

The masses of design/naming/motivation feedback during review is a natural and necessary fall-out of the implement-then-adopt policy, where a review's life or death takes place after a massive investment of time in what is, outside of Apple's built-in Swift development team, often a tiny echo chamber of participants.

For a while the core team would do design reviews for proposals in the queue. These were valuable and helped drive proposals to more suitable choices or allowed them to bow out gracefully when it was clear an idea was not the right fit for the direction and philosophy of the language. I miss those reviews even though I understand how much work they were.

Naming, as nearly everyone agrees, is hard. It is also something that naturally happens quite late. Implementation can focus narrowly on the technical concerns of the solution. Naming must take a wider view, seeing how the solution fits: within the language, within terms of art, and so forth. I think it's only reasonable that a certain level of bikeshedding happen during review because it's only then that the entire picture becomes clear and only then when a sufficient number of participants are actually paying attention.

With regard to naming, while I think we should certainly prefer terms of art, I don't believe we should overly venerate them. A bad decision in one language should not propagate forward indefinitely simply because it established precedent. A cross-language review like the one @Paul_Cantrell presented involves a lot of work and dedication. That's a hard ask when the level of review commitment is so high before we have insight as to whether this proposal or that proposal actually has the strength needed to make it over the finish line.

I'd prefer to introduce a multi-stage review process rather than expanding the current demands to the point where excessive energy is spent implementing, naming, and documenting language features that should not have moved beyond a well-researched pitch. Yes, expand the requirements for naming to include state-of-the-art overviews and yes, add a documentation requirement. But I think the time for these may be after the core team has accepted its problem is well motivated and solve-able and that an implementation has been put forth that ensures the proposal has proof-of-life.

11 Likes

I had a private exchange with @dabrahams that was illuminating, and he asked me to post it here (I think he’ll follow-up by making his reply public shortly):

TL;DR

I’m writing all this to justify my convictions that:

  • Naming things well in programming is completely orthogonal to the grammatical rules of English language.
  • Focus on English grammar is an accessibility barrier for non-native speakers.
  • Overly prescriptive rules are harmful to the living language, hindering creativity and responsible use.

Based on this and other fragments, I might be misunderstanding your aim here, Dave, but you seem to be searching for some kind of rule based system to automate naming decisions.

I don’t think that’s an fruitful direction. To illustrate: I’ve been told several times that for a non-native speaker, my command of English language is above average. But reading the above quote, I had to look up dictionary definition of preposition, to understand what you meant. I’m still not sure I fully grasp your point. People very rarely perform grammar analysis in everyday life. When using a language, we go by our gut feeling and say or write what feels natural, without thorough consideration of all the formal rules. This applies to the use of English and programming languages alike.

You seem to be looking for some kind of amendment to the API naming guidelines that would ground naming decisions in a set of English-grammar-based rules. This approach might have been useful during the big rename, when performing automated conversions form the corpus of Objective-C method names. Even then I recall a linguist pointing out to you that English is inconsistent and shouldn’t be treated like a ruleset.

From Java I remember quite prevalent rule for naming Boolean variables and methods using prefix “is”. From my experience of striving for fluent interface, I find that dogmatic adherence to such simplistic rules actually hinders readability at the point of use. The clarity is achieved by considerate construction of a domain specific vocabulary that slots in naturally into the shape provided by used framework. It’s a result of responsible application of judgment, not automated rules.

Regarding the question from core team about the weighing choices of the different argument labels, the above argument logically leads to choosing the 3rd option, studentBody.containsOnly(gradeIsAPlus):

On the other hand I fully support the concise term-of-art based name .all(satisfy:), including the clarifying argument label. I don’t think we should be going for rule based guideline amendment to justify this choice.

The over-reliance on English grammar creates accessibility barrier for non-native speakers. There’s something wrong when I need to consult dictionary to write Swifty code. The few prescriptive rules we currently have in the guidelines do go a long way and I fully support them. Extending them further with references to arcane English-grammar minutia isn’t really helping and as a second degree effect it creates a justification for bikeshedding, fueling unhelpful forms of pedantry and aggressive lawyering during naming discussions. In spirit of the essay “What Is 'Correct' Language?”, I hope we will reconsider the prescriptivist approach. If an amendment to guidelines is really necessary, I hope we can describe how to strive for fluency by adding more illustrative examples.

I argue for going with even lighter touch: de-emphasize the grammar reference in the guidelines.


If I misunderstood your aim, I’m sorry for wasting your time. If this argument convinced you, feel free to quote me publicly. If your experience lead you to a different persuasion, I’m eager to learn more about it!

2 Likes

I am not; as I have said on the list, there is one prime directive of naming: optimize for comprehensibility at the site of use.

To the degree that comprehensibility is subjective, we need to use some objective criteria to break ties. Surface uniformity, although secondary to comprehensibility, is valuable, as people tune into and take clues from trivial patterns of naming when they occur. One of the patterns that we have tried to maintain uniformly across the APIs (including all of Cocoa, with varying rates of success) is the pattern by which usage that forms an English phrase is broken into base name and argument labels.

My personal aesthetic preference for one form or other is not a sufficient reason to break uniform patterns that exist across the APIs. Therefore, I was hoping to find some patterns—that are precedented in our APIs for good reason, but not captured by the API guidelines—that would justify making the choice I preferred.

I don’t think that’s an fruitful direction. To illustrate: I’ve been told several times that for a non-native speaker, my command of English language is above average. But reading the above quote, I had to look up dictionary definition of preposition, to understand what you meant. I’m still not sure I fully grasp your point. People very rarely perform grammar analysis in everyday life. When using a language, we go by our gut feeling and say or write what feels natural, without thorough consideration of all the formal rules. This applies to the use of English and programming languages alike.

You seem to be looking for some kind of amendment to the API naming guidelines that would ground naming decisions in a set of English-grammar-based rules.

Such “rules” already exist in the guidelines, as one factor among many, and are a fundamental part of how they work. Developing those guidelines was a year-long process, driven by more than five people, aimed at creating uniform patterns across the standard library and Cocoa, which included repeatedly refining automated grammar-based translation of Objective-C APIs into Swift APIs, examining the resulting code to see how readable it was. The use of grammar, among other factors, to make naming decisions is not something anyone involved is eager to relitigate, and is too late to change without creating jarring nonuniformity or breaking vast amounts of code.

This approach might have been useful during the big rename, when performing automated conversions form the corpus of Objective-C method names. Even then I recall a linguist pointing out to you that English is inconsistent and shouldn’t be treated like a ruleset.

I went back and re-read that thread, and I don't understand that to be his point. His objection appears to turn on a broad understanding of what “grammatical” means. When we talk about grammaticality in the guidelines, we mean what I think most people understand it to mean, which Taras calls following “the conventional rules of morphology/syntax of English.” The “semantics and pragmatics” part of what Taras calls “grammatical” are covered by simpler and more prominent guidelines.

From Java I remember quite prevalent rule for naming Boolean variables and methods using prefix “is”. From my experience of striving for fluent interface, I find that dogmatic adherence to such simplistic rules actually hinders readability at the point of use.

I was and continue to be among the strongest advocates for the idea that surface uniformity is never the primary goal. I am constantly telling people that we don't have a goal to put "is" before every Bool or "where:" before every predicate.

The clarity is achieved by considerate construction of a domain specific vocabulary that slots in naturally into the shape provided by used framework. It’s a result of responsible application of judgment, not automated rules.

I'm quite certain nobody ever proposed that good names would be derivable from automated rules.

Regarding the question from core team about the weighing choices of the different argument labels, the above argument logically leads to choosing the 3rd option, studentBody.containsOnly(gradeIsAPlus):

SE-0207: Add a containsOnly algorithm to Sequence
The main argument for #3 is that usage is still quite clear, and it would be better not to try to achieve grammaticality than to go partway there but fail (as in #1).

On the other hand I fully support the concise term-of-art based name .all(satisfy:), including the clarifying argument label. I don’t think we should be going for rule based guideline amendment to justify this choice.

The over-reliance on English grammar creates accessibility barrier for non-native speakers. There’s something wrong when I need to consult dictionary to write Swifty code.

I am a native speaker, and I consult dictionary definitions constantly when trying to choose good names for things, FWIW.

The few prescriptive rules we currently have in the guidelines do go a long way and I fully support them. Extending them further with references to arcane English-grammar minutia isn’t really helping and as a second degree effect it creates a justification for bikeshedding, fueling unhelpful forms of pedantry and aggressive lawyering during naming discussions. In spirit of the essay “What Is ‘Correct’ Language?”, I hope we will reconsider the prescriptivist approach. If an amendment to guidelines is really necessary, I hope we can describe how to strive for fluency by adding more illustrative examples.

I argue for going with even lighter touch: de-emphasize the grammar reference in the guidelines.

Grammaticality is not, and never was, a goal in itself. The guidelines have one fairly gentle directive, to “prefer method and function names that make use sites form grammatical English phrases,” and then several prescriptions for the details when APIs are designed to read grammatically. The intention is that all of the guidelines are weighed, and where they conflict, judgement is used to prioritize them. I'm sorry, but I disagree that any change in emphasis is warranted.

10 Likes

Thank you for your reply. After all clarifications, I agree with without reservation.

I’m also bookmarking your reply for reference when a naming debate goes of the deep end, grammatically… :stuck_out_tongue_winking_eye: