Hacker News Reader

Comment by x87678r | Hacker News Reader

Java is the same as well

Interestingly, documentation that's only type signatures is also a frequent gripe I've heard about OCaml. So maybe this is a universal phenomenon.

However, some people contrast OCaml and Rust in this regard, contradicting the views of the great grand-parent comment: https://news.ycombinator.com/item?id=25111104

So tldr: people don't like writing documentation, and it's hard to make them care.

If you can’t tell a story with text, you won’t be able to tell it with code either. The thing that makes people want better documentation is the same thing that makes it difficult to get.

I remember years ago using Ant as a build tool and the only way I figured it out was to Googlestalk the author. Given enough answers to questions in enough places I finally developed a theory of the system. It was still supremely weird to convince it to do certain things but at least I was able to.

> If you can’t tell a story with text, you won’t be able to tell it with code either.

I couldn't disagree more. Telling a story with words to humans and telling a story with code to a computer are completely different things.

You’re not telling a story to a computer. You’re telling it to your coworkers. The people’s code that’s most frustrating to work with share your philosophy. They are often so convinced they’re right that they can’t even hear constructive criticism. That’s not my opinion, that’s the consensus view shared over lunches and coffees with their coworkers, across many jobs.

Reply on news.ycombinator.com