Approach:
- I’m breaking down parameters one-per-line when they’re complex, contain defaults, and otherwise hard to read.
- I’ve pushed the return token along with the closing paren onto its own line
- In these cases, I’m using Allman to clearly delineate the start and end of the function because otherwise, the opening brace is lost and the params are co-aligned with the code
- I’ve added a bit of extra header whitespace on
CoreErrorandBuildContextErrorto see if that improves readability as well.
I am not designing here to limit vertical space. My goals are:
- Greatest readability and clarity of intent
- Easiest modification
- Space for commenting where needed
Thanks in advance for advice and opinions. Here’s the code:
7 Comments
I’m going to go -1 on this. Either Allman or no Allman, there is no “Allman for functions, no Allman otherwise.” (P.S.: Let the Allman flow through you. Trust the Allman.)
You’re allowed to use emoji in WordPress replies like ?. And this being Swift, you can use enumerations as well, e.g. .Bad(kEvil).
How about indenting the parameters so that they are aligned (one per line) to the right of the opening parenthesis? While it would mean more keystrokes, I think it would add to the clarity.
Response here: https://gist.github.com/Jessy-/5be724763532bc085e43
1. The tuple assignment syntax you’ve been using increases cognitive load; it’s fun, but, I don’t believe, ideal for parsing by a human.
2. The closing parenthesis should not be visually associated with the last parameter, but instead, wherever the opening parenthesis is. This is also true for the generic placeholder name list: I provided an example of what I’m talking about.
3. I move constants that must be initialized in initializers to be after the initializers; I may change my mind on that but I think it makes more flow sense.
I know Xcode can’t auto-format like this. This is a problem with Xcode that needs to be fixed via us all learning what is good and teaching Apple about it.
Erica: Thumbs-up and down aside: I think what you’re doing is wonderful. Thank you for your time and effort. Code can sometimes be as beautiful as the all of UX its behind and can appear as art in itself: the inward expression of the outward. Perhaps philosophical but beautiful code is a joy for a programmer to look at and then work with. Perhaps geekdom, but opening previous software after a while and saying, “Oh my Gosh! That’s gorgeous!” There’s as much natural effort in the code as the software it represents. … It was in fact why I came to your site today as I write something new having seen you work on this recently.
I am not a big fan of /// documentation comments. I prefer /** */ which I write often. It is more readable for me.
Also, I try to keep comments and code up to 80 characters long lines. Here is still a room in every line.
I’m actually really curious as to why Apple follows the /// in all its stdlib work instead of /** */