Line Comments

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 GridLayout(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 GridLayout(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.