5 ms·

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 di

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

cryptoz 8y ago

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

MR4D 8y ago

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

dieterrams 8y ago

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.