Archive for the ‘Musings’ Category

Prototyping CoreGraphics in the Playground

No matter how flaky, I love using playgrounds to prototype Core Graphics, SpriteKit, and many other see-as-you-go technologies. They’re fantastic for building out specific custom content with a bare minimum of coding investment. You get a lot of win for very little time.

I was helping someone out the other day, explaining the strokeEnd keypath (versus the path keypath) and building a playground showed it off to perfection.

Admittedly, it helps to have quick helper code on-hand for quick starts. I have playground-specific setup code, handing me a view controller (called vc) and a centered view, ready to start demo-ing in this one.

I also have a couple of pages of code (like the layer(path:) constructor, the animateStrokemethods, and the schedule() utility off page, in the support module. They’re all highly reusable. It’s a pity in-playground debugging is so dreadful. It would be an ideal module-building tool if not for that: build and explore (and ideally build tests) in a single place, without having to be in a fixed workspace lacking the exploration feature. Adding “convert this exploration into a test” would be icing on top.

I’m disappointed that playground-specific visualizations built for teaching and demos don’t transfer to the debugger for real-world production support. I don’t see any reason why a CGPoint instance should get a pretty graphic representation but a CGAffineTransform, for which I have quite a full presentation, does not.

I can use custom mirroring to produce valuable output for dump, and therefore for printing objects in the debugger but not for debug quicklooks. Plus as far as I can tell the custom NSObject-only quicklooks haven’t been updated in years and there’s no hint of extending this to structs and enums.

By the way, what’s the deal with all the API audits? How long are these going to go on? If you thought updating the app delegate was a minor nuisance, you haven’t seen what’s happened to all the constants and Core Graphics APIs. This update is huge and disruptive…

Return to Sender: My first dive into watchOS

Just wrote my first two watchOS apps. The first, intended to provide voice coaching for physical therapy exercises, was a failure. Timing just wasn’t reliable and the errors built up more and more over a session of repeated counts, holds, and “almost there”/”two more”/”last one” prompts.

The second was a simple D&D dice set and much more successful. (Barring, of course, my miserable sense of interface design.)

It consists of an iOS app paired with a watchOS extension, which runs as its own watchOS app, allowing anyone with an arm and a need for d20 to roll at will.

The WatchOS APIs were disappointing at first glance. For one thing watch buttons use target-action but provide no sense of sender. A single iOS call must be split into 7 calls on the watch:

// iOS. I used tags. Sue me.
@IBAction func roll(_ button: UIButton) {
    let value = Int.random(in: 1 ... button.tag)
    let percent = button.tag == 100 ? "%" : ""
    label.text = "\(value)\(percent)"
}

// watchOS
@IBAction func d4()  { label.setText("\(Int.random(in: 1...4))")  }
@IBAction func d6()  { label.setText("\(Int.random(in: 1...6))")  }
@IBAction func d8()  { label.setText("\(Int.random(in: 1...8))")  }
@IBAction func d10() { label.setText("\(Int.random(in: 1...10))") }
@IBAction func d12() { label.setText("\(Int.random(in: 1...12))") }
@IBAction func d20() { label.setText("\(Int.random(in: 1...20))") }
@IBAction func dPercent() { label.setText("\(Int.random(in: 1...100))%") }

There’s no auto-layout so far as I can tell, so you either “fill” things or you give them fixed sizes. I couldn’t figure out a way to split my buttons into thirds of the available screen space.

Setting a label’s text is a matter of a function call not a property assignment. That was surprising to me. I’m not sure what advantage was gained here beyond violating the principle of least astonishment.

I had to design my app’s interface in the WatchKitApp target but implement it in the extension target. This may be perfectly normal and in-line with other extensions on iOS but I haven’t spent much time there so it raised my eyebrows a bit. You add your app assets in the app, your complications (which I did not build) in the extension.

Right now on my priority list, I’d like to build something similar to the “breathe” app. I don’t entirely know where to start. I need to use a notification system to launch the app at set intervals, n times a day, preferably during the work day, and then use some kind of coached interaction with haptic feedback. My immediate goal is one that has me regularly exercise my sitting back muscles to build up strength.

I’m a bit sad about the timing issues I encountered with my first jab at the coaching app. I may approach that again with a new design as having my wrist count and prompt would be a lot better than having to do all the work myself (I always lose my place) or having to keep my phone nearby.

My need for reps, holds, and rest periods are simple. And while I don’t particularly like the scrolling wheel that seems to take the place of segmented controls, I can live with them.

If you’d like to see my first project (either to be inspired or to offer critiques), I’ve left a copy at github.

Tuple Initialization

I’ve been wanting  tuple-initializable in Swift for Core Graphics, where it’s a drag to always use long and cumbersome initializers when I’m not building production code:

let point: CGPoint = (100, 50)

Yeah, it is better form to use labeled initializers but I’m anyone using CGPoint understands the correspondence between (x, y) coordinates. And I don’t want to just build CGPoint.init(_ x:, _ y:) extensions. I like the tuple form.

Right now, the closest you can get is the silly:

let point = (CGPoint.init as (CGFloat, CGFloat) -> CGPoint)(100, 50)

And that’s (pardon the pun) pointless.

It would be pretty cool to allow memberwise tuples with or without labels in place of  initializers when the tuple field types could be unambiguously determined:

let point: CGPoint = (x: 100, y: 50) 
// instead of: let point = CGPoint(x: 100, y: 50)
let person: Person = ("Mary", nil, "Santos")
// instead of: let person = Person(first: "Mary", middle: nil, last: "Santos")

It may be ugly but it would be hella useful in Playgrounds.

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 mindnode.com:

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 https://apps.ankiweb.net 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
RIGHT = 2
TOP = 4
BOTTOM = 8

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'}

Oops.

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.