Re:Making Code Easy to Understand – What Developers Want (a ...
by johnwatson11218 on Thursday July 28, 2011 @02:15PM
(#2818156)
I have been very frustrated in the past when the only documentation provided was javadoc. In many cases there was an xml that was not documented very well, and subtle things about the classpath that kept the system from working. Often the javadoc is just regurgitating the name of the method. In many cases the javadoc reminds me of the help systems in windows programs. I think I remember seeing a discussion on reddit where they were asking if anyone had ever found an answer in a windows help topic.
[ Parent
| on HN ]
Re:Making Code Easy to Understand – What Developers Want (a ...
by sethrq on Thursday July 28, 2011 @03:47PM
(#2818591)
I agree, no one type of documentation can live in a vacuum. Ideally, javadoc, sample code, tutorials, diagrams, and summaries/explanations would be present for every code base. But in reality I find even a few simple diagrams combined with a insightful description is infinitely better than pages of minimal javadoc.