Hacker News Reader

Comment by simonask | Hacker News Reader

I tend to actually disagree with this attitude, because I see writing documentation as really effective "rubber-ducking". If it's hard and time-consuming to properly document, it's probably hard to use, so extra effort should be spent to actually justify the design, not least to yourself in 6 months. If you can't justify it, it's probably wrong.

View on HN

This really struck a chord with me. Writing documentation is an act of explaining something to others. Explaining something to others is a great way to test your own understanding. If it's hard to explain to someone else, then maybe it's the wrong design.

If you don't through that exercise, you're much more likely to build confusing, difficult-to-use APIs.

> you're much more likely to build confusing, difficult-to-use APIs.

have not found this to be the case with zig in general. you could easily make the opposite argument, that documenting things (especially quirks) can give you license to build confusing APIs.

I think some documentation and a handful of examples would have helped the author of the article. How is the experience when porting to the new standard library improved by not including documentation?

> > you're much more likely to build confusing, difficult-to-use APIs.

> have not found this to be the case with zig in general.

Dunno how general it is, but TFA we're discussing here contains an example, so AFAICS it seems at least a little too common.

100%.

Similar to how TDD forces you to first figure out the API of your code due to the test code being its first client.

Reply on news.ycombinator.com