4 ms·
> 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'
by crazygringo 5y ago
> 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.
- kelnos 5y agoThe 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.
- deleted 5y ago[deleted]
- nytgop77 5y agoFull 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.
- ravenstine 5y agoWhen 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.
- xwolfi 5y agoYeah, 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.
- pmoleri 5y agoI'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.
- nineteen999 5y ago> 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.
- GuB-42 5y agoLibraries 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.
- philosopher1234 5y agoAll code is library code
- gield 5y agoTo 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.
- twobitshifter 5y agoExactly - 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.
- lucideer 5y agoThis 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.