4 ms·
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 i
by probably_wrong 5y ago
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.
- watwut 5y agoTo me the above quote says that author never worked with anything more complicated or more big then simple crud web app.
- ozim 5y agoTo me it says that author is perfectly aware that people are not updating Javadoc comments or normal comments as well.
- pjerem 5y agoIf 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.
- ozim 5y agoIt 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.
- pjerem 5y agoI 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.
- watwut 5y agoWhich is still better then no explanation nor minimal hint at all unless you are doing something simple.
- ozim 5y agoJavadoc 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.
- teknopaul 5y agoHaving 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.
- azemetre 5y agoIs this different from git blame or does @author take the info from git blame for you?
- nytgop77 5y agoSame 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.
- xbp 5y ago> 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