Hacker News Reader

Comment by interactivecode | Hacker News Reader

Can we just agree that more documentation is better? Well named variables, short functions, inline comments, annotations, examples, context, tutorials, types, friendly code owners. Any and all those things are helpful when dealing with unfamiliar code and apis.

Please please don’t discourage anyone from adding these.

View on HN

Also as other people have noted (most notably Fred Brooks and Linus Torvalds), having comments (or documentation) about architecture and data structures is also very helpful.

And literate programming. Well done by Knuth, done by a few other people, but a joy to read when done well.

I think literate programming comes from a time where programming languages where not as high level as nowadays. I don't think there is really any benefit left, and the drawback is the much higher costs of making changes and refactor code, because now you have to move around and keep in sync both code and extensive documentation/explanation.

I think you have to have a more stable goal of the software for literate to work well. But I think most software can be more stable than folks think it is.

Don't get me wrong, some parts of code can easily go through a lot of churn. Hopefully, they would have been confined to a single chapter of a literate attempt. Same as they were hopefully confined to a module or package of a project.

More correct documentation is better. When reading code I'm unfamiliar with, the comments are the only thing I can be certain was never tested.

No, we can't agree. I find the noise of useless comments or documentation can make it much harder to understand a codebase. Sometimes less is more.

Definitely not. Documents grow stale the second you write them, and are often furthermore wrong or misleading. I allow API documentation when it's separated into a different place from the code, but I do not tolerate documentation intertwined with the codebase itself.

Code is hard enough to read without active sabotage taking place, I do not allow PRs to go through if there is documentation in-line with code. The developer must pull it out, and almost always, it can 100% be replicated through better function naming.

Reply on news.ycombinator.com