Bikeshedding Names Considered Harmfull

Evolution Discussion
23

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
24

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
25

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
26

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: