[Joel]: I find this code difficult to read also in part because there are no { }'s delimiting the for loop. I delimit even single line loops like this, and find it difficult to read when other people don't Wimp.
I have little objection to delimiting single-line loops, but I think that it's good practice for any Java programmer to be well-used to interpreting code in either format. Real Programmers™ like to browse Sun's source files frequently, and don't complain when braces are "missing".
Personally, I often omit braces unless I'm working under a style guide that requires them. Why take four lines for a loop (or three with that horrid-looking K&R brace style) when two will do?
[MM]: Does anyone else do this besides me? I put javadoc comments on everything even though sometimes I wonder why. I guess I'm just obsessive compulsive that way. I feel no compulsion to put a JavaDoc comment on any private member. But if a comment seems warrented for clarity, sure, why not.
And what about interface method implementations and overrides? Is it necessary to doc those? I always do. If the implementation has any behavior that was not already specified in the interface declaration, and that behavior is something the other programmers should know about (rather than an implementation detail that's none of their business), then yes. But otherwise I'm content to let javadoc inherit the comment from the super method.
I always use meaningful names for private methods and variables so that anyone looking at the code should be able to surmize their purpose. So am I wasting my time? I agree strongly with this practice. I might use a meaningless name for a
local variable with very limited scope - the canonical example being int i for the index of a for loop. But the moment I need to use that variable name more than
about four lines past its declaration, it gets renamed to something a little more meaningful. My variable name lengths are roughly proportional to the size of the area they're in scope.
[Joel]: All of these syntactic shortcuts are nice, but they seem to preclude the "self-documenting code" concept. This example in particular:
[deleted]
made me scratch my head the first time I read it, even though I understand all the bits and pieces involved. Mmmm... I tend to think it's just that the new idioms aren't as familiar to everyone yet. I think the example shown was quite clear, and preferable to the old code that would be required. Moreover I think that these things
help self-documenting code. Generics in particular are good for saying, in code, "the things in this List should all be Strings", or "this Map uses Strings as keys and Integers as values". Which are both things that usually would require a comment somewhere if using a plain List or Map. And autoboxing improves readability in general, taking away the distracting visual noise of casting and converting between wrappers and primitives, so we can focus instead on where the data is going, what's being done with it. This is good, IMO.
[MM]: Instead of saying in the doc comment, "must be a Collection of String objects" why not check before you cast. Well, javadoc comments are supposed to tell a prospective user of your class everything she needs to know, without her having to look at the actual code. If I write a method that takes a Map parameter and I expect the keys to be Strings and the values to be Integers, I need to communicate that to other programmers somewho that will be visible in the javadoc. Now it's easy:
public void process(Map<String, Integer> map) {
Putting it in the declaration, I've both communicated the intent so that it will appear in javadoc, and I've also effectively put in a check to ensure that by the time my method is invoked, the type is correct. Great, less for me to worry about.
The other thing about "why not check before you cast" - well, what do you want to do if the check is false? A common practice seems to be, ignore the bad data. E.g.:
If the casts don't work, the assumption is that we shouldn't perform the operation on the bad data. Personally, I think code like this is almost always a bad idea, as it just serves to hide errors. If someone's passing keys that aren't Strings, or values that aren't Integers, the best response is probably to report it as an error ASAP. Letting a ClassCastException be trown is one good way to do that (provided you've also documented what classes are expected):
But using 1.5, this is even simpler:
Braces omitted just for Joel.
There's no need for further documentation of the required classes of the key and values, or any additional code to check these things. Much more streamlined, allowing us to focus instead on the doSomethingWith() method, which is presumably where the actual work is to be done.
[ May 09, 2003: Message edited by: Jim Yingst ]
