The Elephant at WWDC

Re:The Elephant at WWDC by tablespoon on Sunday June 13, 2021 @08:25PM (#27497977)

> Explanations of design intent might be the most underrated kind of documentation. There's so little of that nowadays in general, in any technology. Personally, I blame shortened attention spans, the death of programming books, and the rise of Stack Overflow. I'm not familiar with the Apple ecosystem, is it really worse in this regard than others?

I also blame dogmatic misunderstandings that have crystalized around "Agile." Maybe back in the day a some cookbook process specified a lot of useless documentation be created, but many people seem to have thrown the baby out with the bathwater and declared all documentation useless or not worth the effort.

Also some programming books are to blame. IIRC, the book "Clean Code" completely rejects comments because they can get out of sync with the code and therefore be misleading, and "clean code" should be self-documenting. However, all code can ever tell you is what is, it can never tell you why or what was really intended. Also, when you really think about it, method and variable names are comments too, which can get just as out of sync with what's really going on than a comment block.

[ Parent | on HN ]

Re:The Elephant at WWDC by ProfMeowsworth on Sunday June 13, 2021 @10:44PM (#27498731)

To be fair to “Clean Code”, although it’s stance is clearly towards less (superfluous) comments, it recommends using doc strings to document intent.

What it recommends to just delete are comments like

  var speed # the speed

[ Parent | on HN ]

Re:The Elephant at WWDC by tylerscott on Sunday June 13, 2021 @08:41PM (#27498064)

I completely agree. I never understood the argument of docs getting out of sync. If an organization prioritizes documentation then the comments are just as likely to stay in sync as the variables.

[ Parent | on HN ]

Re:The Elephant at WWDC by giantrobot on Sunday June 13, 2021 @11:34PM (#27499002)

In-line documentation getting out of sync is a purely organizational problem. If documentation is valued by the organization inline documentation won't get out of sync.

It's the easiest to keep in sync. It lives in the code it documents. It's in the same version control repo and the same version of the source building a binary can build the docs. If it ever does get out of sync with the code it's the most straightforward to fix because it's the same process for fixing an issue in the code itself.

[ Parent | on HN ]

Re:The Elephant at WWDC by aYsY4dDQ2NrcNzA on Monday June 14, 2021 @12:06AM (#27499199)

And presumably you can track down when the inline docs diverged from the implementation, and who did it.

[ Parent | on HN ]

Re:The Elephant at WWDC by lmm on Monday June 14, 2021 @03:06AM (#27500087)

Documentation isn't automatically checked. Tests and sample code are a better alternative, since you can configure things to give you a build error if they ever get outdated.

[ Parent | on HN ]

Re:The Elephant at WWDC by giantrobot on Monday June 14, 2021 @11:51AM (#27504070)

If you are changing some code that has inline documentation it's your responsibility to update it. If that is not your responsibility then it's an organizational failing. Keeping inline documentation up to date and clean should be part of the organization's coding style guidelines.

Tests are not documentation. They only test a very limited "what" or "how" and give no explanation of "why". If it's closed source software and you're only shipping a binary, the tests do not go with the binaries so they're meaningless to third parties. Sample code isn't much better. Without the organizational pressure to keep it in sync with the code it's demoing and "why" explanations it doesn't provide a lot of useful insight for third parties.

[ Parent | on HN ]

Re:The Elephant at WWDC by lmm on Tuesday June 15, 2021 @05:10AM (#27512868)

Organizational pressure is a scarce resource, it's a waste to spend it on things that you can do with tooling. Keeping tests and sample code up to date involves more than just fixing compilation errors, sure, but the compilation error gets you reading and paying attention to the right piece of material.

[ Parent | on HN ]