Hacker News Reader

The information you are talking about is called documentation and it should exist outside of actual code files.

If you need to read comments to understand code, you don’t know how to read code. Comments can lie, only code is the source of truth, once you gain experience you won’t bother with comments.

View on HN

> The information you are talking about is called documentation and it should exist outside of actual code files.

The file in the OP is Go. In Go, you are encouraged to write documentation and code in one place[0]. The end result is very nice, auto-generated, human readable documentation[1] which is tightly coupled to the code it documents.

[0]: https://golang.org/src/net/http/doc.go

[1]: https://golang.org/pkg/net/http/

Reply on news.ycombinator.com