/** * The number of questions. */ private int numberOfQuestions;
This reminds me of an experience I made five years ago. We recognized that our software was hard to maintain especially by new employees like me. We considered that missing Javadoc comments was one of the problems. So we decided that all new public classes, methods, and fields must have Javadoc comments and that in existing files comments had to be added when the file is edited. JDT has a nice feature to show missing Javadocs as warnings.
(Painting by or found by James Vaughan)
Writing comments is annoying and so – surprise, surprise – few days later two developers independently had the great idea to generate Javadoc automatically. It is worth mentioning that one script was written in Visual Basic. From that time on we no longer wasted time because of missing comments. From that time on we wasted even more time reading stupid comments like “Gets the time”, “Sets the maybe defaulted value” (yes, there was a field maybeDefaulted but I never discovered its meaning), “Default Constructor”, and my favorite “Throws XYZExceptions when an error occurs”. Because Eclipse cannot distinguish between helpful und meaningless comments and show the latter as compiler warnings I used regular expressions and Checkstyle to identify these hidden problems. But that was just the beginning of arms race between people who want to solve problems and cheaters…