This is a very short introductory article to find out if anyone is interested.
So how many of you feel that comments to code, so called "documentation" sucks?
Do you think it's way too often is unreliable, misleading and confusing?
Let's talk about why does that happen, and then how can it be fixed with a simple VSCode extension.
So first, you probably once stumbled upon a code piece like this:
// This function collides Hadrons.
function hadron_collider() {/* ...whatever... */}
Let's say you're a newbie in this project, and you don't know much. And you don't know what's Hadron. You're too shy to distract the more experienced teammates so you start searching the codebase. Of course you're not sure if you can find anything in the codebase about it, but if you're lucky enough, you'll find the description of Hadron somewhere a few thousand lines of code above.
Now wouldn't it be easier if the word Hadrons was a link to the definition? A link, like those that you have in the browser, you know? Something like this:
// This function collides #Hadrons.
function hadron_collider() {/* ...whatever... */}
Then you could click on #Hadrons and go directly to the definition, that would look like this:
/*
@Hadron @Hadrons
In particle physics, a hadron /ˈhædrɒn/ (About this soundlisten)
(Greek: ἁδρός, hadrós; "stout, thick") is a subatomic composite
particle made of two or more quarks held together by the strong
force in a similar way as molecules are held together by the
electromagnetic force. Most of the mass of ordinary matter comes
from two hadrons, the proton and the neutron.
*/
Note the @Hadron and @Hadrons which denote the anchors for corresponding links (#Hadron and #Hadrons accordingly).
So you don't spend time for searching and you don't have to worry if you could find the definition at all.
Now the good news is, you can do that just now, just download the VSCode Extension called HyperComments.
This is only introduction, I am very curious if someone is interested, and if yes, I am going to write about the advanced usage and stuff.
Bonus:
the trick above you can do in any language or file format. However, for TypeScript and JavaScript (C++, Rust, Java etc. support is coming) you can also mention any in-language namespaces:
type Hadrons = Hadron[]
// This function collides #Hadrons
or
class Hadron {}
// This function collides #Hadron
Now, whenever you refactor, you don't have to guess if the documentation may become obsolete. HyperComments will warn you about that by underlining with red color the old names!
Top comments (6)
Pretty cool!
Are there alternatives for other IDEs? My team uses at least 3 different code editors between them.
Also was wondering if there's any standards out there for how you can format your comments, and if you've aligned to them. I know Java has JavaDoc which does a similar sort of thing.
Hi, Emma! Thank you for your interest! Currently there's an extension only for VSCode (and VSCode-based editors). However, if you use the HyperComments notation, then, even if you use the other editors, it's still easier to find defintions of concepts, e.g. you search for
@Hadronand you get exactly one search result - which is the definition.Yep, JavaDoc is one. Then you have JSDoc for JS, which is almost dead, TSDoc for TS, which arguably sucks and was unmaintained last time I checked. For Rust there's RustDoc which is the closest thing to HyperComments, but again, IDE support is close to non-existent and it's less ergonomic
[title](anchor_name).So, I've spent more than a year for research and didn't find anything good. So I'd say that HyperComments could be a new standard, why not? Actually that's exactly what I am going to make happen. This is what's coming soon:
Looks like you've put a lot of thought into it. Good luck!
Indeed. Thanks :-) By the way, what's are the other editors that your teammates use?
Sublime text and IntelliJ
Thanks!