So I've been staring at my source, trying to discern a nicer structure (e.g. find the real structure that must lurk there). And I realized -- in most of
my source, I don't have method comments.

What I have are package documentation, object-level comments, and 
line-level comments. For example: 

  super(new Grid''''''Layout(2,1)); // 2 rows, 1 column

For some reason, if this comment isn't there, I have to think 
and then go look at the javadoc. Because there's a hole in my brain
and "number of rows comes first" keeps falling out of it. 

There are other comments like this in my code. They're very unlikely
to become incorrect (so one of the standard complaints about comments
has no force) and they do make the code more readable (at least for
me).

On the other hand, they're a little like lint balls on a sweater.

WilliamGrosso

''One solution is to use a better editor.  The newer ones can automatically show parameter lists with a single keystroke combination.  Examples include VisualStudio, BorlandJbuilder, and IntellijIdea.''

[note-- the next paragraph was not written by WilliamGrosso] 

Yes, but I think you might be missing the point.  For example, I could number all my functions instead of naming them based on the fact that the comprehensive description of the function is available with a single keystroke from my current editor.  No, I wouldn't really do that -- the point is that the code should stand on its own without the editor.  I believe that the real goal here (pardon the metaphor) is to make a lint-free sweater "with a nicer structure" and not to make a lint-free sweater "glued to an editor."

''Hmm.  The information you're commenting is already there (in the declaration of the function you're calling) -- I'd rather see that information re-used rather than duplicate it.  The comment will go out of date; the function declaration can't.  See SourceCodeInDatabase for another perspective on programmer's tools.''

-----

Why not change to read:
  int rows = 2;
  int columns = 1;
  super(new Grid''''''Layout(rows,columns));
?

----

Is that any clearer ? Personally, they seem about the same to 
me (with a slight preference to the comment because it's 
more localized).

William Grosso

----

Agreed, but this is due to a language flaw - not having keyword arguments. The problem wouldn't arise in Smalltalk or Ada. -- DaveHarris

''Or VB''

Remainder of discussion moved to SimulatingKeywordArguments.