1

I have a very personal gripe with part of Swift Evolution process / culture and I wonder if we can do better…

After recent proposal reviews I feel an onset of burnout due to the endless bikeshedding of names. Note that it is usually a second round of riffing on the name, first being endured during the draft phase.

The culture of Swift Evolution developed, in which API naming discussion takes form of unguided brainstorming session, interspersed with intense criticism duels. I believe this brings in only the worst aspect of brainstorming, which is in and of itself an ineffective waste of time. What we get is massive online multiplayer throw-spaghetti-on-the-wall contest with the minimal barrier to participation. Suddenly everybody feels like they can contribute. Then referries jump in with citations of Swift naming guidelines. Thread length massively balloons. I have yet to witness this train wreck to spontaneously assemble intself into the shape Eifel tower. Therefore I suggest we make some modifications to our process that increase the signal-to-noise ratio, so that our community is more respectful of each other’s time.

These are my suggestions:

  1. Confine the naming discussion to pitch phase only. Proposal review should impose moratorium on name bikeshedding. Confine naming comments during PR to simple statement of agreement/disapproval. I’d prefer a proposal be rejected or returned for amendment by core-team, rather then read 100+ post thread with naming wars again.
  • Spin-up a separate renaming thread if the PR tends toward rejection due to naming.
  • Core-team makes the renaming decision after the review ends.

  1. Proposal authors stick to their guns. It’s your responsibility as proposal author to do the hard work of naming. If you’re unsure, discuss it in then pitch phase. Show your work in the proposal. Don’t ever say “I’m not married to the naming...” during PR! That’s just an invitation for the worst kind of time waste.

  2. Amend the Swift Naming Guidelines to prefer established terms of art from other languages by default over the novel naming, unless a novel Swift name clearly improves over the established term of art in terms of clarity. This has to be justified by sample code at the point of use, not just standalone declarations.

  3. Cultural shift: Police the level of argument. Frequent invalid arguments during naming debates are anecdotal personal confusion over the method’s function without considering:

  • Type information
  • Documentation
  • Ignorance of the problem domain
    To sum up, I find the stance “I didn’t put any thought into this, but my initial impression was wrong.” not worth debating. It is TL;DR - too lazy, didn’t read. Call it out! If you want to object towards a well considered nameing proposal, you must also provide valid evidence: this train of logical reasoning lead me to the wrong conclusion over the function of the method.
    Also fight bad-faith arguments: theoretical discussions looking for a far fatched - but grammatically correct - way of how one might misinterpret the method, if one was deliberately trying to. Though probably intellectually stimulating for the debater, these are especially harmful waste of time. Stop it and call it out!

I value the openness of Swift’s process and don’t mean to argue against participation but the status quo is draining my will. Maybe I’m just getting cranky with creeping middle age... am I the one one feeling this? How would you improve it?

12 Likes
2

I guess it's not only the bikeshedding about name that has such problems...

A simple solution could be that names aren't discussed at all, and everyone just throws in his favorite (ideally, that would need a black box, and not a thread).
We could then rely on Core picking the best one (not necessarily the one brought up by the most people ;-).

A general recipe for improvement could be to split the discussion: Instead of a single thread where promoters and opposers quarrel against each other, there could be a separate thread for each option, and this would be used to distill its advantages -- and only those results are then "presented" to the remain of the community.

2 Likes
3

I strongly disagree.

Naming things is hard, and with source-stability we have to get it right the first time. It would be counterproductive to disallow naming discussions during review, and a waste of everyone’s time to reject a proposal just because someone came up with a better spelling during review.

The way Swift Evolution works, it is not actually incumbent upon reviewers to read the review thread. You are perfectly free to state your own evaluation and feedback on a proposal, then pay as little heed to the rest of the posts as you like.

My experience has been quite the opposite. I have seen numerous instances where the right name was not even thought of by anyone until the review thread, and once it was posted people quickly recognized it as superior. Often these developments only occur as a result of some back-and-forth discussion about possible names.

The pitch phase of a proposal is where people with a strong interest in the feature come up with ideas and an implementation. There are many pitches out there, and most people do not have the time nor inclination to become involved in all of them.

Syntax is equally as important as semantics, so if proposal authors have a strong and principled reason for preferring some spellings over other, they should put as much effort into having the proposal explain the choice of spelling as it does on the choice of behavior.

Conversely, some proposal authors are much more interested in semantics and less interested in syntax, and that is perfectly fine too. There is no sense in requiring authors who care about functionality to go outside their domain of expertise and nail down one specific spelling if they don’t want to.

Being “married” to a naming choice is a bad thing. The goal of Swift Evolution is to improve the Swift language, and a significant part of that is getting the right names for things in the Standard Library.

Nobody should come into a review thread with a “religious” attachment to some particular spelling. It is fine to have reasonable disagreements, but the mental stance of “My way or the highway” can only lead to inferior results, and increased animosity.

Instead, we should all go into these discussions with the attitude of “Here are my ideas, they are the best I could come up with, and I sincerely hope someone else comes up with something even better.”

This is interesting and worthy of further consideration. There is certainly a balance to be had between fluency when reading call-sites, and familiarity of terms of art. They both contribute to clarity at the point of use, which is our overarching design guideline. I am not yet sure where I stand on the matter.

Anecdotes and first impressions *are* relevant data when naming APIs. Type information, documentation, and knowledge of the problem domain can all help with understanding, but clarity at the point of use remains paramount, because code is read more often than it is written.

If anything, I would say that responses like “That name was already discussed in the pitch phase” should not be considered valid during review, unless they actually explain the reasoning. If the name was indeed discussed during the pitch, then the proposal should include a summary of that discussion. If there are valid reasons for disfavoring it, then the proposal should explain them.

Regardless, the review thread gets a lot more eyes than any pitch, so it is to be expected that there may be aspects and ideas that the relatively smaller group which developed the pitch may have overlooked. It is more important to get things right in the end, than for any one person to *be* right.

Bottom line, naming things is hard:

https://twitter.com/secretGeek/status/7269997868

23 Likes
4

I wanted to abstain from replying immediately, but I’m too weak... forgive me!

“Naming is hard!” - agreed. The point is, with naming, suddenly everybody feels like an expert and wants to participate. My beef is with the part of Swift Evolution culture that has devolved into bikeshedding club. Constantly reinventing the wheel and coming up with pile of flat tires on fire. We have to first look at other languages, learn what we can and use that.

Especially the trend to come up with novel names, aiming for grammatically correct English, in the name of “fluency” is absolutely misguided. This usually manifests as multi-word compound methods and argument labels. Viewed through the lens of mathematical notation history, it is outright retrograde. Terms of art from programming must always have priority over this. API design is applied Huffman coding. Conciseness matters.

Another issue is that parts of Swift API are (for historical reasons) inconsistent, asymmetrical or otherwise lacking harmony and it is getting impossible to fix anything. How come that at version 5, we treat all the warts as set-in-stone legacy?

We have much bigger problems with naming, because we are introducing functionality in piece-wise fashion, instead of taking a holistic approach. Because of constant bikeshedding, we are neglecting areas with seismic implications for naming: useful generalizations, that would preempt the itch for sprawling convenience functions. Have a look at this recent PointFree episode. :heart: That’s what SE should be about! Instead we bickering over BS spellings. It is exhausting and I am calling out this aspect of our SE culture as malignant.

4 Likes
5

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
6

swiftEvolution.reduceQuantitativeAmountOfAsynchronousOnlineForumBasedBikesheddingWithRespectToPublicallyAvailableStandardLibrarySymbolNames()

5 Likes
7

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.

8

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
9

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
10

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.

11

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
12

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:

13

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:

14

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
15

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?

16

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:

17

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
18

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.

19

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
20

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