Hacker News Reader

Comment by probably_wrong | Hacker News Reader

I'd like to argue against the author's disdain for javadoc-like comments.

> 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 feel that this is a very inefficient approach to coding. If you tell me what the function does, what its valid inputs are, and what it returns then I don't need to look at the code at all.

More so when I'm collaborating with people outside my area of expertise: a colleague of mine wrote a function to "convert molecule SMILES into their neutralized form". What does it do? Beats me, I'm not a chemist. But thanks to the comments I don't need to know, and I'm grateful for that.

View on HN

Javadoc comments problem begins as soon what is in javadoc stops being true.

So you are usually better of reading the code anyway because you cannot trust that some dev updating code updated javadoc as well.

When something goes wrong I usually have to do is to dig into GIT history and see when and what changes were connected.

Having said that you can spot bad code by its JavaDocs.

The most reliable Javadoc is @author, git tells you the author, @author tells you who the code was copy/pasted from.

Is this different from git blame or does @author take the info from git blame for you?

Same with naming in code.

Names do become misleading. Of course making callstack deep enough, will hide that.

Code reviews have same power to rectify both: naming and comment issues.

> Code reviews have same power to rectify both: naming and comment issues.

Great point.. except for when you're dealing with a lead and/or reviewer that refuses to approve comments because "we write self-documenting code" yikes

To me the above quote says that author never worked with anything more complicated or more big then simple crud web app.

To me it says that author is perfectly aware that people are not updating Javadoc comments or normal comments as well.

If your method documentation is out of date, the problem is not about the doc.

The problem is that someone on your team drastically changes existing methods behavior instead of writing new ones, and by doing that, is changing the behavior every historical caller expected.

I really think that if your changes are so important that they need the doc to be updated, it’s probably that you should write a brand new method. Changes in an already called method should only concern implementation details.

It is not about my team.

It is about people. In the world where team members last ~2 years and move on, expecting that documentation is left not updated is in my opinion perfectly valid assumption.

I was not directing my comment to your coworkers. I was just arguing that a documentation can only be out of sync if the method's intention is changed. And if an existing method intention is changed, your problem is not the out of sync documentation, but the fact you probably broke something in your existing code, not in the years to come, but today.

Which is still better then no explanation nor minimal hint at all unless you are doing something simple.

Reply on news.ycombinator.com