Archive for the ‘Various Frustrations’ Category

Cocoapods and Copyright claims

So what do I do about this? Or more particularly about this: “Copyright (c) 2016 tangzhentao <tangzhentaoxl@sina.cn>”? I don’t mind people using sources from my repos, but I do mind them claiming copyright. I would appreciate advice and thoughts.

Update: On Jeremy Tregunna’s advice, I sent an email: “You are welcome to create Cocoapods using my repositories, but you are not welcome to claim copyright ownership, change the license (BSD attribution in this case), or otherwise misattribute my code. ” I asked tangzhentao to correct the matter immediately.

Update: Tangzhentao responds: “I just saw this problem today in Github and then I went to check my email. Thank everybody to piont out this mistake, especially Erica Sadun. Now I have corrected this mistake. But I don’t know if I really correct this mistake. If not, please remind me, thanks.” There are no changes to the authorship or copyrights, I have asked him/her to update within 24 hours or I will contact Github.

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.

CGAffineTransform constructors and transformers

Core Graphics transforms provide control over coordinate systems, drawing contexts, and paths by enabling you to apply rotation, scaling, and translations. As I’ve been writing about Swift Style, I hope I’m now better able to articulate why I hate the way they’ve been automatically named into Swift.

The current Swift constructors and transformers are:

  • init(rotationAngle: CGFloat)
  • init(scaleX: CGFloat, y: CGFloat)
  • init(translationX: CGFloat, y: CGFloat)
  • rotated(by: CGFloat)
  • scaledBy(x: CGFloat, y: CGFloat)
  • translatedBy(x: CGFloat, y: CGFloat)

Here are my issues:

Confusing naming. “Scale” can be a noun or verb. You can only figure out which one was intended by looking at the translation API. If you have to look at another API to figure out some meaning, the API was written wrong.

In this example, if the two arguments were swapped around and balanced (xScale, yScale), the API would make a lot more sense. I’m not arguing for those terms. I just want to make the point that you should avoid using ambiguous words. This is a classic example of that error.

Missing Types. Why scale and translate by identical meaningless “x” and “y” values? Or rotate by “rotationAngle”? There are better, more exact terms of art and a couple of missing types to support those terms.

Although Core Graphics added CGVector, it is still missing two key types: CGAngle (stores radians or degrees)  and CGScale (stores sx, sy scaling factor pairs).

If I were in charge, you’d be able to initialize a CGAngle using radians, degrees, and π count (for example, 360 degrees is 2π and 45 degrees is 0.25 π). And you’d be able to pull out properties for each of those items as well from a unified structure. A CGScale would provide a natural way to store scaling factors.

Redundancy. If you can come up with a more redundant term than rotationAngle, I’d like to hear it.  rotationAngle uses two nearly identical words to do the work of one: “radians”. It presumes only one confusing initialization style while ignoring other common use cases like “degrees” and “multiples of pi”.

Incorrect Type Use. Although it’s convenient to break out factors into component elements, you’re really translating by a vector or scaling by an (sx, sy) pair. You should be allowed to use these types (for example, scale: CGScale) as well as the broken down member calls (for example, sx:sy:).  This is most notable in the use of CGVector. Although the CGVector type was introduced long after Affine Transforms, transforms were never updated to take advantage of  a semantically richer approach.

Mix and Match Prepositions. Core Graphics includes rotated(by:), scaledBy(), translatedBy(). So where does that “by” belong? In a coherent API, each “by” should either be in the parentheses or outside.

I vote “out”. Doing so enables you to create call families like these, where the specifics of the labels preserve share abstractions and the by isn’t glommed onto the first argument label, throwing off the API’s balance.

public func translatedBy(tx: CGFloat, ty: CGFloat) -> CGAffineTransform
public func translatedBy(vector: CGVector) -> CGAffineTransform

Speaking of unbalanced arguments, scaleX is way longer than y, as is translationX vs y, yet both arguments have equal weight and priority in the calls. Unbalanced labels offer another good indicator of badly designed APIs.

 

Writing updates and asking “Is Github my new Dropbox?”

I’m testing the waters for the first time in using Github rather than Dropbox to coordinate a private project. I’ve used private repos before for material that wasn’t meant for public consumption or to stage material that would then later be released openly but this is the first time I’m testing it out for material that’s substantially not code.

I’ve been meaning to give this a go ever since Github changed its policy to allow unlimited private repositories. I used to be limited to just five in total and I guarded those slots carefully. Under the new policy, I have repos to burn. Today was the first time that I set one up to use in this way.

It feels odd using Github instead of Dropbox as I’m so used to my Github content being primarily open, and Dropbox requiring explicit permissions. Have you tried using Github this way? And how have your experiences been?

The reason I’m testing out Github is that I’m updating iOS Drawing for Swift. I have a week or so to burn while I’m waiting on editorial feedback and tech review on my Swift Style title from Pragmatic. It will take another 4-6 weeks for Addison Wesley to release iOS Drawing rights back to me but I figured I’d get a head start writing some test chapters and get some early feedback about the project while I had some downtime.

I’ve used Dropbox for years to provide material to beta readers and gather their feedback as well as to coordinate material on multiple machines. In testing out Github, I was inspired by Pragmatic’s workflow.

Pragmatic uses a delightfully retro SVN version controlled interactions between editors and authors. (I’ve had to create an SVN/git cheatsheet to remind myself how to SVN all the things.) Pearson/AW in contrast uses Basecamp to manage projects. Basecamp offers a lot of great team features including messaging, calendars, email updates, and so forth, and I’ve been quite happy with it.

Book projects tend to be hefty, especially those with lots of illustrations and sample code but Github has generous file policies. It imposes a 1GB repo limit, 50 MB file warnings, and 100MB file limits.  These are far beyond what I’d need.

I’ve recently changed my overall personal workflow, having been inspired by conversations with editors at O’Reilly. O’Reilly has been pioneering modern, flexible content using markup source. I took my lead from them. (I’m personally using CommonMark instead of AsciiDoc and pandoc instead of Atlas, but the ideas are similar.)

Pandoc has been a pure delight. Even if CommonMark offers less nuance and control than Microsoft Word (however ugly MS Word is, it has power and all the ugly but practical features you need for professional publishing), pandoc allows me to push from manuscript to book in seconds.

I don’t have to use Calibre to build epub, pdf, and mobi output. My code examples are readable and my tables of contents are perfect. I’ve written a bunch of command-line utilities that automate the process of building the ebooks, zipping up archives, and storing copies in a Dropbox beta folder. I still use Dropbox to provide early reader access.

I built Swift Style‘s first draft using this workflow, writing in MacDown, an open source macOS Markdown editor. I like MacDown’s side-by-side display but, to be honest, for material of any size, it has no way to keep the text and output in sync, especially once you introduce illustrations.

If I find some time, I’ll probably try to mess with the source to add this functionality because once you drop the ability to see your edits as you add them, the utility loses a lot of its charm but that’s a project for another day.

In the meantime, I’m just getting settled into Github for this project. A lot of my work steps are similar: I start by pulling and wrap up by pushing but now it’s to the repo, and not to Dropbox. Github offers more version control than Dropbox’s undelete functionality and I don’t have the same worries about filling up my quota.

I’m curious: Are you using Github for non-coding projects? And how has that worked out for you? Did the DNS incident a few days ago make you rethink? Or are you committed to this kind of collaborative tool? Let me know. Thanks!

Solving Mathieu’s Phone: The mystery of disappearing gigs

The other day, Mathieu’s 16 GB phone suddenly had no space. Even after rebooting, even after reformatting (and not restoring from backup), all his spare bytes were being sucked into a black hole.

He had no songs, few apps, a modest number of photos, and under a gigabyte of space available, making him unable to compile, load, and tests his apps.

cvgmmpaxeaeooco

Each time he deleted one of his apps, the space would mysteriously fill up within a few minutes, adding to the ever increasing “other” bar in iTunes:

unspecified

This delete-then-lose-space behavior made me think that iCloud was trying to store files locally on his phone to reduce cloud access. I suggested that he disable iCloud and sync just the bare essentials like contacts, calendars, and notes. (Mathieu has a paid 300GB iCloud plan.) Sure enough once he logged out and rebooted, over 7GB of space was freed up and he was able to use his phone again.

I’m not super-familiar with iCloud so if anyone can further explain how this works, and how to set up the phone to limit it from glomming space, I’d sure appreciate being able to pass that along. Thanks!

Responding to bad errors with bug reporting

Soroush K writes,  Here’s one annoying thing about Swift 3. The line

let location = geofenceNotifier.locationDataStore
    .cached?.first(where: { $0.id = locationID })

should be using `==` instead of `=` but the error you get is `Cannot call value of non-function type ‘Location?’`. It should give me an error saying “Hey, `id` is a `let` so you can’t assign to it” or “You’re not returning a Boolean.” and not “we’re trying to call `Location?` as a function.

While I can see where the team was going with this error I agree that it probably reflects the wrong most common error case. When you encounter bad Swift errors, file a bug report at bugs. swift.org and explain why you think it’s a bad error and what you think should have been a better approach.

Announcing tmdiff

For all I know this already exists and I just was unable to google it up. Assuming it doesn’t, tmdiff allows you to perform a command line diff on a text file against a time machine version.

Repo: https://github.com/erica/tmdiff

Usage:

Usage: tmdiff (--list)
       tmdiff [offset: 1] path

The list option just lists the dates for the backups in reverse chronological order. Supply a path to diff, e.g.

tmdiff Style600-Control\ Flow.md

It defaults to using the “but last” backup offset of 1. If you want to use the most recent backup, use 0 instead, or any number moving further back in time as the value increases:

tmdiff 0 Style600-Control\ Flow.md
tmdiff 3 Style600-Control\ Flow.md

I hope this is handy for someone out there on the opposite side of the Intertube, especially since version control is baked into stuff like TextEdit. Do let me know if you use it.

Update: See also github.com/erica/tmls and github.com/erica/tmcp. The former runs ls, complete with arguments. The latter performs a nondestructive copy with the Time Machine date appended.

How to add a bookmark in Sierra Safari

I’ve been super-frustrated trying to use ⌘-D to add bookmarks ever since I installed Sierra. The browser only wants to add my bookmarks to existing folders. I, on the other hand, want my bookmarks to go to the main list until I have time to weed and sort them.

This morning, I finally found out how to save bookmarks to the Bookmarks list in Sierra:

  1. Hover your mouse over the left side of the URL bar (aka the smart search field). A circled ⊕ appears.
  2. Do not click it. If you do, you’ll just add the page to the reading list. Instead, click-and-hold until a contextual menu appears.
  3. Now move the cursor down to “Bookmarks” and click there.

safariscreensnapz001

Yeah, it’s a lot stupider than just typing ⌘-D, but at least it works the way you expect. If bookmarks and ⌘-D are working right for you, please let me know. I can’t think of anything I might have done to mess up Safari but at least it will be a data point to help.

The unbearable Swiftness of web search

Swift proposal SE-0086 removed the NS prefix from many types in the Swift Foundation library. In doing so, it moves Swift away from its Cocoa roots to establish a cleaner language palette to work with. Swift adheres to a philosophy that type names should be clear, consise, and without needless prefixes.

The result are names that are intuitively obvious, easy to understand, and a real pain to search for. If you thought tracking down information on Swift filters, conversions, mapping, strides, streaming, and notifications was hard, then you may appreciate what it’s like to search for Swift Bundle, Operation, Process, or Thread.

Swift (the language) is now gaining sufficient traction that searches are far more responsive for programming than they used to be. Still, it  helps to throw in an extra word or two like codesample, or type to focus your search. You may also want to limit searches to, for example, “site:apple.com”.

And, yes, you can always pick up one of those Swift Calendars and read about Swift Dates. Swift wasn’t named after a certain pop star. It just sometimes acts like it was.

p.s. For Dave Abrahams: COW optimization.

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.

IMG_1521

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.)

IMG_1526

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.

IMG_1523

(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.)