Literal Oddities

I’m busy writing about literal style (prefer literals when you can but add typing) and stumbled across a form of binary exponentiation that I hadn’t used before.

Do you know what these two Swift literals evaluate to?

0x15p1, 0xA.8p2

I’ll give you a hint. The numbers must start with hex values and may include elements past the decimal point. The p exponentiation means “multiply by 2 raised to this power”, so 0x15p1 means 15 hex multiplied by 2, and 0xA.8p2 means A.8 hex multiplied by 4.

Of course you can just type them into a playground but where’s the fun in that?

let dent = 0x15p1

If you still don’t know the answers, I’m pretty sure that a pair of ordinary lab mice might.

Style: How would you fold this?

Here’s the stdlib implementation of zip:

public func zip<Sequence1 : Sequence, Sequence2 : Sequence>(
  _ sequence1: Sequence1, _ sequence2: Sequence2
) -> Zip2Sequence<Sequence1, Sequence2> {
  return Zip2Sequence(_sequence1: sequence1, _sequence2: sequence2)
}

So once again, I’m trying to figure out how I would fold this rationally. I’m not a huge fan of the parameter list on a single line like this, especially when there are both external (_) and internal labels involved, generic parameter types, and a complex return type.

I was thinking of something more like this:

public func zip<Sequence1, Sequence2> (
    _ sequence1: Sequence1,
    _ sequence2: Sequence2
)
    -> Zip2Sequence<Sequence1, Sequence2>
    where  Sequence1: Sequence, Sequence2: Sequence
{
    return Zip2Sequence(_sequence1: sequence1, _sequence2: sequence2)
}

This update moves each parameter to its own line and splits off both the return type and the constraint clause. What do you think? How would you personally fold it? Let me know and thanks.

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.

My terrible no good horrible updating day

Good news: There should be an updated version of Playground Secrets awaiting iBooks customers. Apple is looking into why my updates over the summer did not get relayed to customers. This issue does not affect anyone who bought from LeanPub.

Expect another Playground Secrets update soon beyond this. I’m still tweaking to the final Xcode/Swift 3 release. Look for revision 3.5 to debut shortly. It will have “Swift 3, Xcode 8” at the very top.

Good news: I’m also updating Documentation Markup. A preview of some of the changes I address is here. I’m probably going to include at least some of the points I made in my essay about past you and future you.

Good news: The response to the Swift Celebration Bundle has been so strong that I’m extending the sale until at least the end of this week. Thank you everyone!

Bad news: Some nice Xcode features have gone away. Remember this, which picked up information from the structured markup?

screen-shot-2016-09-19-at-2-48-51-pm

It’s now gone. Xcode no longer shows the abstract for the selected match.

Badder news: Xcode fuzzy completion is so relaxed and shows so much stuff that it can be really hard to find the API you actually want. There can be literally dozens of pages of completions for certain APIs.

Good news: After months of going back and forth with Bluehost technical support, they seem to have finally found something slowing down responsiveness. Hopefully this site will be slightly zippier. Not promising great responsive time but there should be fewer 504 errors and database errors and timeouts.

Helpful non-news: Make sure you check your iTunes Connect account to review your old applications. Not all notices are getting sent about the 30-day “you must update this old app” period. If you have some older titles, take some time to check on them.

Helpful extremely non-news: For whatever reasons, you must adhere to standard iTunes Connect dimensions when uploading Book screenshots. The books side of things won’t tell you what they are, but they are: 1024×768, 1024×748, 768×1024, 768×1004, 2048×1536, 2048×1496, 1536×2048, 1536×2008.

Xcode 8 Document Coding Enhancements

Now that I’ve gotten Swift 2 to 3 ready and out, I’ve turned my attention to Swift Documentation Markup. I’m updating the book with both Swift 3 examples and markup enhancements. Xcode has added some great new features although as you’ll see there’s still work left to be done.

Xcode’s automatic doc-comment skeleton command is super handy. Move the cursor to any symbol and select Editor > Structure > Add Documentation (Command-Option-/). Xcode scans the symbol you’ve chosen and adds a doc-comment outline including named parameters and return types if they exist.

screen-shot-2016-09-16-at-10-46-30-am

You may want to add further comment features like notes, warnings, authorship, dates, and complexity details, but the basics provided by Xcode form a great place to get started.

One Xcode feature that’s just launching is support for treating closure parameters as first-class documentation elements. Xcode’s default documentation doesn’t include closure parameters, as you see in the screenshot that follows.

screen-shot-2016-09-16-at-11-06-41-am

Swift’s new “no  labels for function types” means that many developers will not include the internal declaration arguments that I use in this example for the action parameter.

By adding internal arguments like (_ line: String), you can extend your documentation. Xcode picks up and formats that information into a special closure parameter box, subordinate to the closure that uses that parameter. Here’s an example that extends the code documentation you just saw:

screen-shot-2016-09-16-at-11-09-13-am

Swift’s native comment schema suggests that Xcode could potentially add further support. The schema includes nesting parameters, return values, and throws document comments, as promised in this commit:

screen-shot-2016-09-16-at-11-15-05-am

As far as I can tell, the only feature that is currently supported by Xcode is the named closure parameters, demonstrated above. Here’s what the schema looks like from Swift’s point of view:

<!-- In general, template parameters with whitespace 
   discussion should not be emitted, unless direction 
   is explicitly specified. Schema might be more strict here. -->
  <choice>
    <element name="ClosureParameter">
      <optional>
        <ref name="Abstract" />
      </optional>
      <optional>
        <ref name="Parameters" />
      </optional>
      <optional>
        <ref name="ResultDiscussion" />
      </optional>
      <optional>
        <ref name="ThrowsDiscussion" />
      </optional>
      <optional>
        <ref name="Discussion" />
      </optional>
    </element>
    <element name="Discussion">
      <ref name="BlockContent" />
    </element>
  </choice>

Unadopted Swift enhancements don’t end there. There’s further work to be done to support changes provided by Swift but not picked up on by Xcode. Here are examples from the Swift language change log and from Swift proposal SE-0111:

  • Three new doc comment fields, namely - keyword:- recommended: and - recommendedover:, allow Swift users to cooperate with code completion engine to deliver more effective code completion results. The - keyword: field specifies concepts that are not fully manifested in declaration names. - recommended: indicates other declarations are preferred to the one decorated; to the contrary, - recommendedover: indicates the decorated declaration is preferred to those declarations whose names are specified.
  • This proposal introduces two new document comment fields, MutatingCounterpart and NonmutatingCounterpart. These replace the roles of the former mutable_variant and message arguments. Under this scheme, @discardableResultwill not use arguments. Documentation comment fields will, instead, supply usage recommendations in both directions.

Swift From Two to Three on iTunes and Leanpub

screen-shot-2016-09-15-at-9-06-29-am

Swift 3 is a major, breaking language change. Are you ready to make the jump? Let “Swift from Two to Three” help you along the way. From migrating your code, updating your style, and adopting new Swift features, this book ushers you into the newly refreshed language. Learn what changed, why it changed, and how you can update your code using this hands-on guide that covers all the major difference with plenty of examples and insight.

Now available from iTunes and Leanpub. Buy all three and save 30%.

Sending a sincere thank you to everyone who helps support my blogging and independent writing by purchasing books.

Swift 3.0 is released

Raise a glass, everyone! Ted Kremenek writes on swift.org

Swift 3.0, the first major release of Swift since it was open-sourced, is now officially released! Swift 3 is a huge release containing major improvements and refinements to the core language and Standard Library, major additions to the Linux port of Swift, and the first official release of the Swift Package Manager.

Congrats to the whole Swift Team and all the volunteers on Swift Evolution, Swift Dev, Swift Build Dev, and everyone else who pitched into the effort.

I’m finishing up edits on Swift 2 to 3, and it should hit the Bookstore within the next few days.

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.

Finishing up Swift From Two to Three

twothreescaled

I’m getting close to wrapping up my latest little self-published Swift book. Like Playground Secrets and Documentation Markup, the book will be available on iTunes and LeanPub. It’s written for anyone who has stayed in Swift 2.3 so they could keep shipping code but who now is looking to move towards Swift 3.

Here are some sample pages to give you a feel for what’s coming up.

As always, if you have any feedback or requests, please let me know. Does this sound like a book you might purchase? I’d love to hear from you.

Thanks again for all the support you give me, my blog, and my books. It’s appreciated beyond measure.