Hacker News Reader

Comment by crazygringo | Hacker News Reader

> If you wonder what the method does, or what the valid input range for a parameter is, you are better off just reading the code to see what it does.

I couldn't disagree more.

I was recently programming a library where some parameters could be 0 or greater, some parameters necessarily greater than 0, some parameters could be Infinity, others couldn't...

Similarly, if one parameter is set to zero than another parameter will have no effect...

JSDoc kept the whole thing sane. "Reading the code" would take several minutes to figure out the answer in each case, which would be wasted time in my book.

JSDoc is awesome. Not every function needs it, but plenty do.

View on HN

When I started out programming I was taught that the code should "document itself" and that comments were an anti-pattern to writing good code. It took me a few years realize how idiotic that was and deprogram myself.

It's one of those things that sounds nice, but once you've moved beyond a certain level of complexity you realize how impractical it is. The fact is that "good code" is often in the eye of the beholder and not everyone has the same skill or vision, so they might as well write a comment about what something does and the intent behind it rather than leave others guessing.

Yeah, while it's true that a misleading comment can cause more harm than no comment at all, saying code is the documentation is cheating

Either we admit we'll never budget maintaining the comments metadata on top of the code, and embrace that risk for the cost reduction it provides, or we do document for real and maintain and review and fix regularly at a cost.

But saying we dont need to do it because it s already done is a quick stunt that everyone saying it knows is dishonest.

I've seen people refactoring the code just to avoid writing a single line comment, like it's a dirty thing to do. After the refactor the new code is probably more readable, but not as good as it would have been with the comment.

> was taught that the code should "document itself" > comments were an anti-pattern to writing good code

I've been programming in one form or another since I was 8 years old (around 38 years) and this was obviously incorrect to me back then, even though I wasn't sharing my work with anyone else, and hadn't heard this concept.

Years later I was astounded to move into a "modern" dev environment where people (developers, devops) parroted this line regularly. As you say it's nice in principle, but in reality relying on it proves to be impractical.

Exactly - please do javadoc style comments. “It’s not an API” is not the way to look at it. You have to look at it as - I will not be the last person to use this code block. You don’t want to force someone else on your team or your replacement to dig into your method to figure out what the parameters are and the correct usage when they see it used somewhere. Having a javadoc pop up an illuminating description is very valuable. As the code base gets bigger you can even just look at the exported javadoc to figure out if someone (maybe you) already implemented the method you are thinking of. The part of the article rejecting javadoc sounded like it was for only ephemeral projects and not a mature code base that’s been handed down.

The worst, though, is when a comment tells you the valid input range, but it's wrong, because someone later changed the code and didn't update the comment. While this doesn't happen frequently, I've gotten bit by it enough that I will generally at least take a cursory look over the function body to verify that the comment is still correct.

I wouldn't say this makes the comment useless, but it does reduce the usefulness. And this might end up biting someone who has decided to trust the comments.

Full agreement.

Unfortunatly it is a story, that is set to repeat 3 times.

There is a similar tragedy of outdated documentation.

And then the final part of the trilogy is named "outdated and even misleading naming" (vars/functions).

In all cases, one should have same amount of trust as with weather forcast or politician's speech. Trusting 100% would be naive, but complete dismisall would be foolish as well.

To add onto this, the documentation of a method is often a contract. If the documentation is good, the actual implementation of the method shouldn't matter to someone only wanting to use that method. Even moreso, the implementation could change: maybe there is a more concise or efficient way of implementing the contract.

This is great if you're using a loosely typed language (like JS), but I think the need for this is why things like Typescript are gaining in popularity.

I used to love the eslint-enforced jsdoc in a repo I maintain, but since we embarked on a TS migration, it has become painfully redundant in 90%+ of cases (there are cases where the jsdoc contains extra commentary/context that TS doesn't cover, but I think those cases are covered by the author's other comment types).

So given the above, I think it's notable that you are referring to JSDoc (and by extension JS) whereas the author is referring to Javadoc (and by extension Java). The language choice is particularly important here.

Libraries are an exception. Here, from the article, talking about Javadoc.

> These comments may be useful for API:s exposed externally, but in an application where you have access to all the source code, they are mostly useless.

All code is library code

Reply on news.ycombinator.com