Writing self-documenting Swift code | Hacker News Reader

Writing self-documenting Swift code

swiftbysundell.com

73 pointsingve18 comments

The hole point of documentation is lost in the concept of something "self-documenting".

Documentation needs to be describing the actions of the program on a different abstraction level/perspective than the program itself.

Something can be easy to read and to understand but it cant be self documenting unless it actually literally writes it own documentation it being a sentient AI or something like that.

I agree. As a primarily Android-focused developer, I understand Swift and I know how to make an iPhone app. But there nothing as infuriating as being handed a 30k LOC iOS app's source code and being told that the code is the documentation, and no, there is no other documentation (because that would be silly! just read the code!).

No, if you can write 30k lines of any computer language, you can at least write a 2 pager in English/preferred human language describing the architecture and other details of the code. Ridiculous that people expect code to be documentation to the point of not writing a single sentence in human language about what the code does or how it works.

You would receive a README explaining how to get set up, what pattern was used and how the classes reflect to that. Like "*Fetcher is a static object used to fetch Model objects over the network".

Should not be more than 200 lines. Because everything over 200 lines gets flagged as a warning </pedantic>

I agree, and consider code without comments to be unfinished work, but writing code without comments is not the thrust of this article.

It's just writing clearer code, structured to make more things utterly obvious (to the human, but in many cases also to the compiler).

Code written like this will still need some comments/documentation, but it won't need as much because more things will be completely obvious.

You are conflating comments with documentation.

Comments are low-level, documentation is high level.

"self-documenting" removes the need for comments, not documentation. Ironically.

I don't think "documentation" has such a narrow definition.

There are various forms of documentation, from terse READMEs to formal specs. Comments in the code are just one of the many forms documentation can take (in some cases, the only one).

In the intro paragraphs is this sentence, which you would probably agree with. It sets the tone for the whole article.

“Regardless of how you feel about writing (and reading) documentation - I think most of us agree that we should always try to make our code, and the APIs we design, as easy to understand as possible.”

The idea behind self-documenting code is that much documentation that would normally be required because the code is so poorly written, becomes unnecessary if the code was rewritten to more clearly express what it’s doing.

It is absolutely true that code cannot be fully self-documenting, and the idea of writing self-documenting code isn’t to suggest that it can be. E.g., why things were done a certain way is not readily expressible through code. And it’s often helpful to give a plain-language overview of the purpose and responsibility of a class, for example.

In my experience, writing as “self-documenting” code as possible is vastly preferable to a culture which cares more about writing comments for everything than writing readable code. People end up writing obligatory but worthless comments; comments are strewn everywhere making it even harder to read or skim code; and you end up getting vastly more comment rot.

Great read!

I'm going to steal that use of 'typealias' when defining a closure that uses @escaping. Those method definitions are always so messy looking, this really cleans it up.

Type alias is a poor alternative for true primitive types. Like (pseudo code):

    primitive Dollar: Decimal // no mixing with euros
    primitive Meter: Double // no confusion with miles

You can do the same in Swift with typealias _but_ it will happily accept you passing in Euro where Dollar is declared because they’re both Decimals. This doesn’t happen in languages like F#.

You can define a struct with a single field of type Double.

True. I think there was a Money cocoapod that used your trick. But you can’t do anything with them you would normally do with the base type unless you add a ton of logic.

Also in F# you get the type Meter/Hour if you divide Meters by Hours. Which multiplied by an Hour value gives you the distance traveled at that speed in that time.

As someone writing occasional Swift code, this is very encouraging and educational. It makes me wish for a Swift-related e-zine with quality articles like these.

Well just FYI this guy himself produces nearly that; I have him in my RSS reader and he produces great articles like this on a weekly basis.

There is also: https://swiftweekly.github.io

Nice article, more about code maintainability than documentation (like others pointed out).

Also not too focused on Swift, so useful also for other languages.

A lot of these examples are smelly IMO. Your colleagues in marketing are not debugging your code base. You work with other developers who definitely know what Ints and Strings are, so when you disguise these basic types in structs or type-aliases, you are basically doubling up the API you and your colleagues are working with.

Well, you're not only making it easier for your colleagues in marketing to be able to make a code change (hey, it happens more than you might think!) but you're also making it easier for your future self to come back to the code base without having to remember as much.

Most important, though, you are structuring the code in a way that provides better actionable understanding of the intent not only to the humans that work on it, but also your intrepid robot buddies, the Swift compiler / static analyzer. Who happen to be extremely helpful allies in this particular language.

In Swift, I would recommend using dedicated types like AccessToken and RefreshToken, instead of plain strings, 100% of the time.

Nice article. Minor nit: unit of gravity is NewtonsPerKg.

Reply on news.ycombinator.com