Erica Sadun

Where technology meets something or other

Diving into the big world of API Guidelines

A ridiculous amount of mailing list effort has gone into discussion of SE-0023 API Design Guidelines. You’ll find the original guidelines here at swift.org, and I highly recommend you pop over and read them. For the most part, I really like the guidelines. I also think some bits about naming and labels are too prescriptive.

The document is broken into four parts: fundamentals, naming, conventions, and special instructions. I have basically no issues with the fundamentals: be clear, prefer clarity to brevity, comment everything. I’ve written Swift Documentation Markup, a book that takes these to heart and expands on how you can do this. Same no-issue stand applies to section four, special instructions.

The second section focuses on naming. Part one “promoting clear usage” says: avoid ambiguity by adding just enough words, cut away words that aren’t needed, augment weakly typed parameters with a role noun. I don’t have any problems with this part, and I could see myself diving in and exploring the philosophy more. The third part “use terminology well” is also innocuous.

Part two of naming though is “be grammatical” and I have quibbles with this section. I think Apple would be well served with just dumping it entirely. I started writing up a long, exhaustive response to this part but it started spiraling out of control.

The issue lies in what distinguishes naming things: should you name noun-y things with nouns and verb-y things with verbs? That’s probably the best approach, honestly, and one that would avoid the well-intentioned details in the current guidance.

Or should you evaluate whether methods mutate instances? Should you take all side effects into account and differentiate them from pure functions? And that doesn’t even take property-vs-method naming into account (not to mention any naming that might hint at complexity).

I honestly think Apple should drop this section like a hot potato rather than trying to force it to work with their current stab at it.

I also have issues with Conventions, specifically the bit about argument labels. Again, I’ve written up an overwhelming response over at github, where I make a case for why logically related arguments should weigh more heavily than the “drop the first argument” approach and why groups of related calls should emphasize their connection using initializer-like naming.

I currently have nearly a book’s worth of notes about these kind of issues, because I was planning on putting together a small self-pubbed book about Swift Style that I started working on earlier this winter. I got diverted by the the SE-0023 review but now I think I’m going to go back and start kicking away at my take on this again.

You can find some of these guidance posts here:

etc. etc.

Tweet this Post

Comments are closed.