Hacker News Reader

Comment by christophilus | Hacker News Reader

I’ve been misled by comments so often that I now literally don’t see them. They’re like banner ads on websites. My brain just doesn’t register them anymore.

They get orphaned by slightly wonky merges. The underlying code gets updated or refactored, but the comments remain. When they are correct, they’re useless 90% of the time (at least in codebases whose linter requires doc comments). Even the accurate comments tend to drift with age and become inaccurate unless they’re carefully maintained (which they almost never are).

It’s really hard for me to figure out the balance.

For exceptionally good codebases (Redis, SQLite come to mind), the comments are a godsend.

For mediocre codebases, the comments are largely a waste of time at best, misleading and time-wasting at worst. And most of us, I suspect, are working on mediocre codebases.

View on HN

Rust libraries use comments for generating documentation and testing. Here is an example of such documentation: [1]. It is difficult to believe that this code would be better without comments.

At least classes and public methods should have comments (except trivial ones).

[1] https://docs.rs/chrono/0.4.19/chrono/naive/struct.NaiveDateT...

What is generating this HTML page? I'm always looking for something like this can help automatically generate documentation from code comments; it's very easy to get buy in for "update the docs when you update the code," much less so for "go through the comments for every piece of code you touch and double check they're still relevant." It's one of those things everyone nods at then promptly ignores.

Something like this with a discrete task that can be checked on code review would help immensely, I think.

I'm interested to know the answer as well. I've used org mode in the past for literate programming and document generation, but I'm starting to think that generating docs from comments is also a good option.

Adding a mechanism to publish the docs (maybe part of CI/CD?) would make maintenance way easier, it's something I would love to test out.

I’ve been working on a tool to do this based on a simple Python file watcher, web server and https://casual-effects.com/markdeep/ It just turns regular code into markdown code blocks and /** comment contents pass through to the markdown —> HTML pipeline. A little JS websocket and you get an auto-updating preview from any editor to any browser every time you ctrl-s.

Not much time to work on it lately. But, I’ll Show HN when I put it on Github.

It's rustdoc: https://github.com/rust-lang/rustc-dev-guide/blob/master/src...

> Rustdoc actually uses the rustc internals directly. It lives in-tree with the compiler and standard library. This chapter is about how it works. For information about Rustdoc's features and how to use them, see the Rustdoc book. For more details about how rustdoc works, see the "Rustdoc internals" chapter.

`cargo doc`

docs.rs runs it for every crate (rust library) uploaded to crates.io.

When actually working with rust, I recommend running `cargo doc --open` semi frequently. It generates that documentation from all your dependencies, and your own code, links it all together (with search no less) and opens it in a browser.

Note that it only uses doc comments, which are distinct from normal comments (/// instead of //, only allowed in certain places, //! Instead of /// to apply to the parent item instead of the next item).

Haskell does this as well, using Haddock [0] — e.g. all content on this page is generated from comments in the standard library: https://hackage.haskell.org/package/base-4.16.0.0/docs/Prelu...

[0] https://haskell-haddock.readthedocs.io/en/latest/

HEavily used code will evolve good comments, as a product of multiple smart people using and improving the same code.

Bad codebases are ones that basically are throwaway or depreciating assets. As you say, we practically all work on these except the lucky few.

Reply on news.ycombinator.com