Strip Excessive Comments

I've always found that until I remove all the javadoc lines (and many of the inline comments), I can't make much progress grokking even relatively simple code, and I think I've finally figured out why: I can't rephrase the code (refactor?) easily. You know, the stuff extracting a variable or a method, basically reducing it to its constituent parts. I suspect it might largely be a mental block of some kind, but when I see a 15 line function, I get scared off, even when 8 lines are comments and 5 more are blank.

I understand the javadoc adds some significant constraints, but that makes me wonder about the usefulness of javadoc in general... until proven otherwise, I go by the function name and parameters to find what I need. Admitedly, the javadocs are good for that, but then so are a lot of smart editors. Then there's the case of implementation details - i.e. method foo must be called before you bar this - but then I find I prefer to look at the source: why must I call foo first?

-- WilliamUnderwood

I HaveThisPattern too. I am fairly new to the game too so maybe it is a problem not a skill. Not sure yet. :) But I find removing comments an integral part of RefactoringForGrokking?. And as much as I know I can never believe comments, I still can't stop myself from reading them. That's why they distract me so much! -- PaulMitchellGears

(from MassiveFunctionHeaders)

But saying CommentsAreNotAllowed is just plain barmy.

(EditHint: Is there a more appropriate page for this comment ? BigThingsIntimidateAllOutOfProportion? ?)

when I see a 15 line function, I get scared off, even when 8 lines are comments and 5 more are blank.

I'm starting to notice this sort of thing even outside of programming.

When I see a WikiPage that's more than a few screens long, I often give up halfway through, but when the same content is split into 2 or more pages, I'm happy to read the whole thing and add some comments, and/or edit it to make it more concise.

Many people look at the size of a book and are scared off from reading it, even though they may enjoy reading the same amount of text when it is serialized in a periodical.

Many people look at the price tag of some tool, and are scared off from buying it no matter how useful it may be (even if it would pay for itself in a year).

Many people are scared away from learning programming, because of the perception that it will take "too long" to learn, no matter how useful it may be.

-- DavidCary

Rather than removing comments from the source altogether (unless the comments are wrong, I consider this a questionable practice), might it be better to configure your IDE to hide them from you? If that isn't an option right now, I'm sure it could be added to EclipseIde or IntellijIdea without too much difficulty. Or, if syntax highlighting is available, change the color to something close to the background color.

But remember... other people on the team may find the comments valuable. Unless the rest of your team agrees, deleting comments because you find them to be a distraction is surely an AntiPattern.

--ScottJohnson

That's similar to what I tried to save (you beat me to it):

The human brain grasps best those things it can see in one glance.

I've heard people rave about editors with a "folding" feature that hides dross (as defined by the user in some cases); if one viewed code with something that could hide/unhide comments at the click of a button, it would probably help. (For all I know, both emacs and vim support such a thing; I've never checked.)

I had that thought and rejected it. It would mean we put in necessary comments, fold them, forget them, and let them drift out of sync with the code because we never look at them. if it's important enough to be there, it's important enough to keep visible. if it's not important enough to keep visible, it probably shouldn't be there.

That does beg the question of what "should" means, which depends on context. For instance, it might be better to leave in a comment that is excessive for you if you know this code may have to be maintained by a less experienced programmer who would, in fact, need it. Of course, if the code can be refactored to elimiate all need for the comment, regardless of the audience that's preferred.

-- SteveJorgensen

I believe that this may be missing the point a little. JavaDoc should, after all, be describing in depth the inputs, outputs, and side-effects of a method. It should explicitly not be discussing the implementation. If you're refactoring code within a method then almost by definition the JavaDoc becomes more useful because it should remain completely true after the refactoring, requiring no changes.

In fact, when refactoring any code, I would suggest that the first step be to read the code and determine exactly what its doing. The JavaDoc block would be a good place to note this, although it should already be correct. After completion of the refactoring, you should check to make sure that your code doesn't behave any differently (to external users). Again, since you have to have some kind of notes in order to do this, JavaDoc should serve that purpose.

If your refactoring means that you're changing the comments then either you're doing a lot more than what is normally considered refactoring, or your public comments are exposing your private implementation.

-- RichardStanford

One of EclipseIde's built-in refactorings is "ChangeMethodSignature?", so having to change comments doesn't imply doing more than is normally considered refactoring. If you find you need to document side effects, consider removing side effects. If you find you need to document inputs, consider renaming the inputs to better reflect your intention. If you find you need to document outputs, consider renaming your methods to better reflect your intention. -- EricHodges

ToNeedComments

CategoryCodingIssues