Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

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.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: