I like writing comments. But at the same time comments kind of suck. In this post, I want to outline some ways we could improve this.
I like writing long comments that have references to code and conversations, that explain complex things, that have diagrams, etc, etc. But comments are just text. Just raw, unparsed, unformatted text.
And this is bad!
Comments are just a very internal form of documentation, and documentation is usually written in some markup language (like markdown, in the case of Rust). We render it, we allow it to link other parts of code. So why don’t we have anything like that for comments? Is it because comments predate documentation and markup languages, and we just continue to treat them like we always treated them?
tip: in Rust, you can use paths in inline links in documentation to mention items, like
more on this in the
One of the things I like about newer versions of JetBrains IDEs is that they can render documentation:
I think that we should treat comments similarly — allow some kind of formatting inside them and then render them in IDEs. I especially want to be able to use inline links, because commit hashes, message ids and such often cause links to be very long.
I wish comments were treated better than we treat them right now.