4 ms·

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 3

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.

dep_b 8y ago
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>
veidr 8y ago
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 8y ago
  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 8y ago
    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).

dep_b 8y ago

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>

veidr 8y ago

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 8y ago
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 8y ago
  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).