Archive for the ‘Musings’ Category

Pronouncing “Tuple”

A tuple is a finite ordered list of elements. It is presented as a parentheses-braced, comma-delimited list. In Swift, you can use them as stand-alone heterogenous lists of values or pass them as arguments to functions and closures.

A tuple is pronounced “tupple” (TUH-ple), not “two-pull”. It’s a shortcut pulled from “double, triple, quintuple, sextuple, octuple”, etc. Yes, please note that “quadruple” doesn’t fit with the others and is not used as a basis for speaking the word. Rules about long and short “u”s that apply to other English words are also not relevant to this case.

In Swift, a tuple is analogous to an anonymous struct. Its members are indexed numerically (.0, .1.2, etc). You can also use labels to access members by name:

let point = (x: 5.0, y: 2.3)
print(point.1) // 2.3
print(point.y) // 2.3

Swift 3.0 and later no longer supports splatting, so you cannot decouple a tuple from a function call. You can read more about this in SE-0029, which disallowed the ability. Before the change, you could call a function either with its direct arguments or by passing a tuple:

func foo(a : Int, b : Int) {}
foo(a: 42, b : 17) // still allowed
let x = (a: 1, b: 2)
foo(x) // no longer allowed in Swift 3+

The continued work on SE-0110 is still resolving on how tuples and closures interact.

The word “arity” describes the number of members in a tuple. (It also describes the number of arguments or operands accepted by a function, method, or closure.) The examples above use an arity of 2. You can call this a “2-arity tuple” or the shortcut “2-ary tuple”. Some shorten that further to a “2-tuple”.  All are acceptable.

Some fun facts to finish with:

  • A figurative tuple with an arbitrary arity is an “n-arity” or “n-ary” or “n-tuple”.
  • A tuple with a variable number of arguments is variadic.

The problem with Swift Playground localization

Starting in Swift Playgrounds 2, you can now use localized strings to guide the narration of your interactive lessons. As the screenshot above demonstrates, you can used localizable markup to provide the most appropriate text for titles, introductory text, and feedback.

However, what you can’t do is localize Swift members. Your French and Chinese consumers must tell Byte to moveForward(), not avancer() or 向前移动().

One of the guiding principles of the Swift language is demonstrated in its embrace of unicode for identifier symbols. This approach accommodates programmers and programming styles from many languages and cultures.

Xcode 9 has introduced major advances in code refactoring. It seems an obvious win to allow that technology to be applied to Swift Playgrounds 2, enabling identifier localization.

That’s because identifiers play such a key role in Swift Playgrounds. Unlike standard development tasks, where it’s unnecessary to create idiomatic APIs like IUContrôleurDeNavigation, the point of Swift Playgrounds is to teach and instruct. It uses small, limited, controlled API exposure, nearly all custom and supporting of the teaching story.

The anthropomorphized Byte character acts as a stand-in for the learner coder. And in doing so, it should communicate with commands that this coder identifies with, turnLeft and moveForward, not incomprehensibleForeignPhrase1 and evenMoreConfusingForeignPhrase2.

I think this is an opportunity waiting to happen, and I can’t imagine it would be all that hard to implement given the expansive identifier suite and the limited API visibility presented in a typical playgroundBook.

What do you think? Is it too much to ask for a localizable.Members.plist?

Bug reporter complaints

I wasn’t part of the bug reporter preview but having used it today, I’ve got to say that I am not a huge fan of the updated interface. It may be pretty, but for me it’s harder to use. I’d rather see icons and names at the start of the entry screen than scroll through three pages of iconless text (and their subtables) as I try to recognize the phrase that best matches my issue.

It’s funny because this design is a clearly cognitive mismatch between how I used to find the right items, which was just a matter of a single-screen scan, and trying to construct or detect the right verbal phrase that now matches the target issue. The new system is hitting the wrong part of my brain.

If you look at it, it’s laid out very nicely, with big clear areas to enter text and the “drop a screenshot” system is vastly improved over the old system. (Nice job there!) I like the font choices, can live with the sickly purple, and a lot of thought has gone into streamlining issue entry.

That said, the whitespace feels like there’s too much there, the left-to-right range of field width is too hard to scan to review the information you’ve entered, and as I mentioned before, the ‘What are you seeing an issue with?” tables are a little too much for me to process.

If I were to redesign it, I’d:

  • Change the wording to be more business-like: “Classify this issue:”, not “How would you classify this issue?”. “Affected Product or Area”, not “What are you seeing an issue with?”. “Bug or Suggestion”, not “What kind of issue are you reporting” (with the bias being towards ‘bug’, since that’s the primary purpose of the tool.) “Reproducing the issue”, not “What steps can we take to reproduce this issue”, and so forth.
  • In the prompt text, I’d eliminate weasel words. “Step-by-step instructions to reproduce this problem”, not “Please provide a step-by-step set of instructions to reproduce the problem (if possible).”
  • I’d cut back massively on the vertical whitespace, allowing more of the report to be seen at once. There’s just too much floaty gray for my taste.
  • I’d apply one of the “optimal line length” studies, which suggests anywhere between 50 and 75 characters per line for text (which is most of what this tool provides) and 80-160 characters for code entry. (I’d also consider a code-specific “related code” field.) The current width is about 98 characters if I counted correctly. It is very hard to track from the right back to the left while maintaining vertical positioning.
  • I’d explicitly mention Markdown/Common Mark support for bullets and numbering, as well as other markup.
  • I’d change the Suggestion/Bug toggle into either a radio control or a visual toggle with Bug, which should be to the left, pre-selected.
  • I’d massively increase the size of the “Cancel/Save/Submit” buttons and move them from the bottom bar to the main field under attachments.
  • Finally, I’d add a specific call out on completion. Thank the developer for taking time from their busy workday and express appreciation for participating in the radar process. Enroll them either in a rewards-for-radars program or a random giftcard giveaway for the month. It’s a small price to sweeten that “Radar or GTFO” message and it lowers frustration of typing into a big, faceless, low-feedback system.

Those are my thoughts. What are yours?

That API thing

Today, Nikita Voloboev was trying to wrap his head around how this whole Cocoa/Cocoa Touch API thing worked. The conversation started when he asked, “Is UIKit part of Cocoa?” The docs weren’t really giving him an idea of how it all worked. After a few minutes back and forth, he derived this concept using the tools at

It was a good first guesstimate even though it doesn’t exactly capture Apple’s API design. I hopped into Preview and sketched out this diagram instead. (And yes, some day I may write a book about all the cool things you can do for free in Preview):

I explained how the API families shared certain frameworks but that the frameworks weren’t uniformly implemented across all the platforms within that family. Cocoa and Cocoa Touch, I tried to explain, were the API families specific to four operating systems: macOS, iOS, watchOS, and tvOS.

I pointed him to this definition, which I pulled up by a web search for define cocoa apple:

Cocoa is Apple’s native object-oriented application programming interface (API) for their operating system macOS. For iOS, tvOS, and watchOS, a similar API exists, named Cocoa Touch, which includes gesture recognition, animation, and a different set of graphical control elements.

He then threw that definition into another mind map, which he uses to keep notes. This was a cool and unexpected way of exploring new knowledge:


I’m fascinated by his learning toolset, which includes both mind mapping and Anki Decks (see and this explanation of Spaced repetition.) I tend to turn to paper and pen, or other familiar tools, to take notes or to share.

What kind of tools do you use to explore and explain new areas of learning?

Enter the Python: Peeking at a language

Last week, I wrote about how I set up Xcode to run Python. It’s been working great. Xcode may not be everyone’s cup of tea, but I love it. Syntax highlighting, familiar keybindings, symbol completion. I couldn’t be happier. A lot of people pushed me to use Pycharm community edition, but while I’ve installed it and tried it a few times, I keep going back to Xcode. Warts and all.

I haven’t logged many hours in Python but it’s been a fascinating language experience. Let me go all metaphor on you. Way back in the 90’s there was this show called “Sliders“, about a bunch of people moving between parallel worlds. Almost everything was the same from world to world — normal humans, trees, buildings, whatever — but there were always fundamental differences in the culture and the people that always reminded you that you weren’t home.

Python is the Sliders version of Swift, the one where Chris Lattner was never born. Everything is eerily familiar and nothing is quite right. Where are my value types? My generics? My type extensions. Let me throw out another metaphor — one that will probably resonate with even fewer people: Python is the language version of the Nethack Rogue Level, where you enter “what seems to be an older, more primitive world.” It’s all familiar. Nothing is exactly the same.

This morning, I attempted to extend a type. I’m working with Anki’s Cozmo robot SDK, which is written for Python 3.5.1 or later. I’m trying to reconfigure many of the basic calls into more appropriate chunks suitable for teaching kids some programming basics.

Instead of focusing on asynchronous callbacks and exceptions, I want to provide really simple blocks that extend the robot type API in a way that hides nearly all the implementation details. I’m trying to build, in a way, a Python version of Swift Playgrounds but with a real robot. (And it’s going well, but more about that in another post.)

What I found was that Python really doesn’t want to extend types. You can subclass. You can compose. But so far, I haven’t found a way to add an extension that services an existing type. When I asked around, the Python gurus on freenode recommended I stop worrying about polluting the global namespace and embrace freestanding functions as needed.

Oh, my delicate Swift sensibilities! Adding global functions and constants? Cluttering the global namespace? I find myself clinging to Swift conventions. I create enumerations and type my arguments:

class Direction(IntEnum):
    '''Permitted driving directions.'''
    forward = 1
    backward = -1

def drive(robot: cozmo.robot.Robot, 
    direction: Direction = Direction.forward): ...

The Cozmo SDK defines its constants like this:

LEFT = 1
TOP = 4

I don’t think I’m in Swift-land anymore.

A lot of the things I like most about Python appear to be fairly new, like that ability to type arguments. I’m assured by some Pythonistas that this is almost entirely syntactic sugar, and there appears to be no type-checking, inference, or casting applied to calls.

I thought I would really hate the indentation-based scoping but I don’t. It’s easy to use (start a scope with a colon, indent 4 spaces for that scope). It reads well. It’s clean. Non-braced scoping ended up being a complete non-issue for me, and I mildly admire its clean look.

I’m less excited by Python’s take on structured documentation. The standard is outlined in PEP-257. Unlike Apple’s Swift Documentation Markup, Python markup doesn’t seem to support specific in-line tool use in addition to document generation. I’m sensitive to how much better Swift creates a structured system for detailing parameters, error conditions, return types, and descriptions, and how it scales from types to functions and methods to individual instances and provides Xcode integration.

So much in Python is very similar to Swift but with a slight twist to it. Closures? Lambdas are in there. Mapping? That’s there too. Partial application? Seems to be. Most times that I reach for a tool in my existing proficiencies, I can usually find a Python equivalent such as list comprehension, which is basically mapping across sequences and collections.

I’m sorely missing my value types. One of the first things I did when trying to work through some tutorials was to try to create a skeleton dictionary rather than type out full dictionaries for each instance. I quickly learned Python uses reference types:

# the original dict was more complicated
studentDict = {"name" : "", "tests" : []} 

joe = studentDict # create joe
joe["name"] = "joe"
bob = studentDict # create bob
bob["name"] = "bob"

# reference type
print(joe) # {'tests': [], 'name': 'bob'}
print(bob) # {'tests': [], 'name': 'bob'}


In any case, I’m still really really new to the language given my full-court-press on finishing Swift Style. As much as I wish I were writing this code in Swift, I’m glad that I have the opportunity to explore Python and hope I get to spend some time with Scala in the near future. This project is offering me a lot of valuable insights about where Swift came from and increased appreciation for the work the core Swift team put in to give us the language we have now.

Swift Holy War: Comments are not an Anti-pattern

Got into a debate yesterday about this write-up by developer Andrew Warner. His “Beware the Siren Song of Comments” suggests that developers delude themselves because comments detract from code quality:

Comments decay. They aren’t compiled, and they’ll never get executed at runtime. If they become out of date or incorrect, no test is going to fail and no user is going to complain. Programmers work around them out of fear that “somebody might need this comment or it might provide some value in the future”, pushing them along far after they’re useful (if you can even argue that they were useful in the first place).

His recommendation?

[Y]ou don’t have any excuse to write comments. Give these methods a try, and I promise you’ll have a cleaner codebase that’s easier to maintain.

I don’t claim that comments should counterbalance bad design decisions like poor naming or flawed algorithms. I do believe they play an important role in good coding practices — whether or not your code is meant strictly for internal use or to be consumed as APIs.

As I discussed on this blog a few weeks ago, there’s a big difference between the you writing code and “future you”, your team, and anyone else reading code. Here’s what I have to say about commenting in Swift Style:

Comment, comment, comment and while you’re at it, write tests. Tests can save you the whole “What I was doing here?” because you can just look at what is broken and what you expected to work.” It’s better to write less code and make up that time by explaining the code you did write better.

Sure, it helps to leave in a “TODO:” where it counts (“the performance is really bad here”) but while you’re at it, try to leave a few ideas about what exactly is going wrong, and what hypotheses you have rolling around your soon-to-be-extinct neurons. Past you understood things. Future you is clueless.

It always costs less to fix things in the past because you’ve invested in uploading the full design into your brain. Re-upping that design and getting back up to speed involves huge penalties.

Comments can explain the non-obvious, the tricky, or the counter-intuitive to a reader: This is intentional. This thing affects that thing. This data is not validated at this stage. Responsibility for this process now passes to this delegate. Comments enable you to establish what your assumptions are at which points in code and they allow you to comment on design qualities.

Comments create a record of intent. They may mention approaches that were tried and why they were abandoned. They may discuss how design decisions came to be — what paths were explored and why some of those paths weren’t chosen in the end.

Comments allow you to colocate thoughts with the code they refer to. Commit messages are helpful but I don’t think a commit message is  the proper place to document workarounds or unexpected behavior. Plus version control history may not travel with source code, if the code is reused in another project.

Comments provide a bread crumb trail of design decisions that aren’t kept in working memory and cannot be intuited just from reading code or scanning tests. Unexpected complexity is one of the things you’ll want to comment about. In fact, commenting on the unexpected is important because the alternative is essentially a bug.

Structured comments add another layer of utility, supporting API consumption. Markup allows these special comments to automatically convert into highly formatted local documentation supporting another set of readers beyond code review, debugging, maintenance, and enhancement.

Comments don’t just paper over bad design and coding. They document a process of making code right, supporting future reading and modification. Good comments reduce the mental effort needed by readers each time they review your source, enabling them to focus more on specific tasks like “how to I add this feature” rather than “what the hell was going on here”. While good code can at times be “self documenting”, that doesn’t mean it always is (or even usually is) self documenting.

As stepping stones to “past you”, good comments document what you were thinking and why you did things the way you did. Your past design decisions should never be a mystery or a burden placed before future readers of your code no matter how brilliant or insightful you expect them to be.

Reconciling Past-You with Future-You

It’s a basic truth in programming. When you get interrupted before coming to a really good stopping point, you are screwed. Life happens. And reality is cold and harsh.

Sure you intend to comment about what needs fixing and where you left off, but past you always provides less reminding than future you desperately needs. Future you can be really dense.

The very worst moments happen when you break off in the middle of refactoring. That grand design you had in your head, the one where every piece fit together like a stunning mosaic? It’s gone. Duct tape, band aids, and a bit of WD-40 are all you have to look forward to.

Past you and future you are never friends.

If you’ve ever written a comment like “// The methods in this class probably don't work the way you'd expect based on their name“, you know what I’m talking about.

Never underestimate future you’s stupidity. Comment, comment, comment and while you’re at it, write tests. Tests can save you the whole “What I was doing here?” because you can just look at what is broken and what you expected to work.

It’s better to write less code and make up that time by explaining the code you did write better.

Sure, it helps to leave in a “TODO:” where it counts (“the performance is really bad here”) but while you’re at it, try to leave a few ideas about what exactly is going wrong, and what hypotheses you have rolling around your soon-to-be-extinct neurons. Past you understood things. Future you is clueless.

It always costs less to fix things in the past because you’ve invested in uploading the full design into your brain. Re-upping that design and getting back up to speed involves huge penalties.

Remember these core lessons:

  • Future you is thick as a plank.
  • Comment as if you are writing for a particularly dimwitted stranger, especially when that stranger is you.
  • Build tests. Add examples. Fill in structured document fields. The more you comment now, the less grief you’ll experience in the future.
  • Past you is a total jerk.

When did Ikea ditch the sunshine, rainbows, and unicorns?

The new Ikea catalog arrived yesterday. Is it me or have they turned over their design to some crazed Swedish goth intern? My new catalog feels more Hitchcock and “Vogue Editorial” than “Affordable purchases for people who wish they could fix their out-of-control lives.”

Ikea’s gone from cute girls in a colorful apartment (top, 2015) to psychotic butcher knives that think they’re actually vegetables (check out that shadow) and this recurring weird backdrop thing, which makes me think they couldn’t afford an editor to crop the photos properly (bottom, 2016).IMG_1527

Suddenly, they’ve transitioned from simple product images inspiring you to simplify and organize  your life to a kind of nightmare clutter scenario where all reason has fled and you apparently must buy every product available from the company and store them in the open without drawers, cupboard doors, or any break in sanity.


Look at that poor woman standing at that kitchen island. Her entire body communicates the tenseness from barely having a spare inch of counter space, banging her knees against all the junk on the two shelves, the shame of putting your dishes out for public viewing. Inside, she’s screaming “I will never get my life under control and it’s all IKEA’s fault! For just $499!”

(By the way, I love the LED light at the middle of the right page of the 2015 catalog. Mine is black, not red, and it’s perfect between my two computer monitors. Folds up out of the way when not in use.)


Apparently 2016 is the year of dark spaces, drawn blinds, and Carmen cosplay. You can pretend to die of consumption in the gloomy shadows of your living room, while dressed in red and practicing ballroom in the  (perhaps) 2 square meters of space between couches.

And can you think of anything scarier than your sofa actually being your home. Last year, a beautiful, open plan living room, with a family happily getting work done on the laptop and reading to a kid. They seem happy, their plants seem happy, the lightness and brightness no doubt makes them feel free and open and relaxed. Compare that to this year.IMG_1525

No, Ikea, a sofa is not the home. And who are all those strange people who wandered into this poor woman’s life just to stare at and harass her?

Here’s Elsa. Elsa thought she’d have a lovely relaxing time, putting up her feet before picking up the kids and stopping by an organic locally sourced market for take out to eat while perched on a variety of ottomans and sleeper couches.

Who would ever have expected an entire gang from Twitter to take up residence on the other side of her monster sofa, laughing at her, mocking her, and critiquing her lounging style. That gang of four sure think Elsa is a hoot. And all at the same time, creepy Helmut from down the road just stares at Elsa with unrequited longing. I think perhaps he’s humming ska songs from the 1980s to her.

Poor Elsa. This is what comes of living in the middle of a photographic studio, without doors to keep out strangers, no storage for clothing, a ragtag group of floating sofas for the young ones to sleep upon, and three mysterious remote controls to remind her a time when she had a real house to call home.

Oh Ikea. It’s time to say goodbye to 2015, with its misty bright hopes for a world of knotty pine. 2016 has arrived with its dark bleak dystopian furniture and a bookshelf that looks like an insurance liability court case ready to happen.


(As a side note, I had no idea that sleeper sofas crept out of their homes while we were at work to embrace that secret 24-hour life. It must get crowded at the bowling alley and at the local microbrewery when affordable furniture sits around, drinking lager, and sharing the stories you thought were kept secret.)

The names of things

Last night, someone was asking what you call the things created by types. My take on the subject is this: Classes, structures, and enumerations are constructs. You create new instances by calling a constructor, even when building things that aren’t reference types.

I avoid calling reference types “objects”. I stick with instances, following the Swift Programming Language’s lead, e.g. “Use the init?(rawValue:) initializer to make an instance of an enumeration from a raw value.” and “Create an instance of a class by putting parentheses after the class name.”

A big naming challenge derives from what do you call the thing that stores a value. The Swift Programming Language has this to say: “Use let to make a constant and var to make a variable”, which is not at all helpful because you end up saying “Declare a variable or constant”, “use the variable or constant as a parameter to the function”, etc, etc.

While constants and variables are “bound symbols”, “value bindings”, or just “bindings”, those are hard names to use in writing. “Create a value binding of 5” doesn’t communicate the way “create a new variable or constant and set its value to 5” does.

This is why, I prefer to stick with variable to describe both in any indeterminate situation. Constants are really immutable variables, egregious oxymoron and all. And, as Joe Groff points out, constants are still variables according to the mathematical meaning of the term.  It’s not a great solution but nearly everyone gets it.

So unless you’re going for precision, go ahead and declare a variable to store that value. If you don’t or won’t mutate it, the compiler will remind you to mark it as a constant. Long live “let variables“. It may not be technically precise but it does communicate expressively.


Trailing commas, open source, and community participation

The wave of support, kind words, and tweets after the rejection of SE-0084, which introduced support for trailing commas in declarations and at call sites, has been very kind but rather misses the point of open sourcing the Swift language.

While Apple’s Joe Groff provided a strong voice of support for SE-0084, there were few concurring list members willing to speak up for it.

John Siracusa wrote, “Having used, more or less continuously for my 20 years as a professional programmer, both a language that allows trailing commas and one that does not, I come down pretty strongly on the side of allowing trailing commas (for all the reasons already stated in this thread). If it means requiring a newline after the last comma to make some people feel better about it, so be it.”

Brent Royal-Gordon also voted in favor, “I was skeptical of this until a week or two ago, when I had some code where I ended up commenting out certain parameters. Removing the now-trailing commas was an inconvenience. So, +1 from me.”

The remaining community votes were almost entirely negative, with a special award for honesty for Chris Lattner, “I personally find that style repulsive.” In this light, comparisons to Perl and C that show up after the review period has ended don’t add support or change the outcome.

Unless you’re willing to participate in the Swift Evolution process and speak up for or against proposals, the outcomes may not reflect your specific development needs. The best arguments for or against a proposal are real world code, measurements of use in public and private libraries, and pragmatic use-cases that express why a proposal should be adopted or not. Swift language changes should fix real problems and must be demonstrated with real data.

The best evolution reviews include thoughtful analysis of how a change affects existing code bases, improves outcomes, and compares to other programming languages. They should analyze how the proposal fits with the specific feel and direction of the Swift language. A surprising quantity of review feedback ends up as “+1” or “-1”  one-liners, which don’t really help guide the evaluation of a proposal’s merits.

Evolution members are welcome to post their reviews publicly or to directly contact the review manager with private feedback. I have participated privately in a handful of reviews and publicly in others. I’ve abstained from reviewing many proposals (there are now over a hundred of them) when I had no strong feelings or no background to evaluate a topic.

Swift Evolution, as all open source projects, offers an imperfect process:

  • There is far too much on-list traffic to keep up with. It helps if you’re specifically dedicated to documenting the language and its process, which is an extreme outlier case.
  • Participants are self-selected and skew towards people who dedicate time to debating language design; that time must naturally trade off from work, spending time with family, watching TV, or engaging in other lifestyle activities and hobbies.
  • On-list consensus may not match the consensus in the wider developer community and there’s often quite a strong backlash against attempting to measure the temperature of that wider community.
  • If you think “best editor” wars are bad, you haven’t seen the bikeshedding over multi-line string grammar.

To be clear, Swift Evolution is not “design by committee” as some mass wave of crowd consensus. The Swift process was designed from the start to be both opinionated (“Swift is an opinionated language”) and  focused given the circumstances or community involvement. At this point, I can’t remember if Apple wrote this or I did, but “maintaining that coherent vision for something as complicated as a programming language requires both coordination and leadership.”

The ultimate responsibility for adopting changes lies with the Swift core team, which acts as Swift’s internal star chamber. The team establishes the strategic direction of Swift. Core team members initiate, participate in, and manage the public review of proposals and have the authority to accept or reject changes to Swift.

The majority of work and discussion take place on the highly-trafficked Swift Evolution mailing list. This list provides the platform to propose, discuss, and review ideas to improve the Swift language and standard library. There are few participation rules, mostly to do with adhering to a respectful code of conduct.

Using a mailing list establishes a public record of all proposed changes and their ensuing discussions. Participants can explore archives to determine whether a topic has already been discussed and/or voted on, and what the arguments for and against those changes were. The Swift Evolution archives are available at and

Having votes go against your preferences is part of the reality, and there are often some very good underlying reasons why some proposals go the way they do that are obvious on the larger scale than the smaller (to simplify the language, to enhance reliability, to obtain more accuracy, precision, and speed, because of the internal compiler limitations, etc.) The core team feedback at the end of the review period explains why each vote went the way it did.

That said, each proposal needs its champions. The process can be tedious and needs to be driven from a pitch through drafts, from pull request through review. Supporters should be available through the review process to answer questions, update text, offer code.

With Apple standing behind Swift, its impact is both large and loud. If you love coding and language design, there’s rarely an opportunity like this to become part of the process and help influence its outcome.