Question

I’m writing a Java Application for my final year CS undergrad project at uni. In the previous years we have been told that using CheckStyle for our code is a MUST. However, I’m finding that using the default CheckStyle configuration requires me to write a JavaDoc for EVERY thing. Even obvious instance fields and methods where the name and the actual code is sufficiently descriptive of what that piece of code does, requires me to write JavaDoc comments.

I honestly find this repetitive and just cluttering my code. Without all of these comments I find my code MUCH more readable and shorter which gives me a better overview when I need to look over classes etc.

The problem is that, if checkstyle highlights it as a problem (missing JavaDoc) and we have been told to use CheckStyle with no exception, then I suspect I would lose marks which is the last thing I want. I quote from the excellent book:
Martin, Robert C. (2008-08-01). Clean Code: A Handbook of Agile Software Craftsmanship (p. 54). Pearson Education (USA).

The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration. So when you find yourself in a position where you need to write a comment, think it through and see whether there isn’t some way to turn the tables and express yourself in code. Every time you express yourself in code, you should pat yourself on the back. Every time you write a comment, you should grimace and feel the failure of your ability of expression. Why am I so down on comments? Because they lie. Not always, and not intentionally, but too often. The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong. The reason is simple. Programmers can’t realistically maintain them.

I can’t say how wholeheartedly I agree with the above. The comments are just nothing but mess in my eyes. Where relevant , I DO have comments.

So, my question boils down to the following: Should I stick with my own belief and knowdledge/advice gained from reading the above book, or should I comply with the CheckStyle standard and eliminate the risk of being marked down from the lack of JavaDoc comments ?

Answer 1

You say:

However, I’m finding that using the default CheckStyle configuration requires me to write a JavaDoc for EVERY thing. Even obvious instance fields and methods where the name and the actual code is sufficiently descriptive of what that piece of code does, requires me to write JavaDoc comments.

And also:

I did ask my supervisor who said it would be best to stick to what Sun proposes i.e. the default checkstyle config.

These two statements are not consistent.

Here is the actual, traditional, ancient Sun coding conventions document (as revised in 1999):

• http://www.oracle.com/technetwork/java/codeconvtoc-136057.html

The section on comments does say:

Discussion of nontrivial or nonobvious design decisions is appropriate, but avoid duplicating information that is present in (and clear from) the code. It is too easy for redundant comments to get out of date. In general, avoid any comments that are likely to get out of date as the code evolves.

It does not say that every member requires a comment.

I think that makes it pretty clear that comments are not required for either “obvious instance fields” or “methods where the name and the actual code is sufficiently descriptive of what that piece of code does”. Either your supervisor’s instruction or your interpretation of it errs in drawing a equivalence between the Sun coding conventions and the default Checkstyle configuration.

It’s also worth bearing in mind that the Sun coding conventions were written by and for the programmers who were writing Java itself. That is a quite special kind of work; they didn’t just have to produce code that worked, and was comprehensible by maintainers, but because they were making a standard library which would be distributed only in binary form, which was understandable, and indeed in many cases fully specified, by signatures and comments alone. I think it’s pretty silly to apply rules developed in the 1990s for the implementation of Java itself to application code written today. It’d be like living your life according to Leviticus.