
Writing self-documenting Swift code - ingve
https://www.swiftbysundell.com/posts/writing-self-documenting-swift-code
======
callesgg
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.

~~~
cryptoz
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.

~~~
veidr
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.

~~~
markrages
You are conflating comments with documentation.

Comments are low-level, documentation is high level.

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

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

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

~~~
dep_b
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#.

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

~~~
dep_b
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.

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

~~~
veidr
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](https://swiftweekly.github.io)

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

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

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

~~~
veidr
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.

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

