agreed. comments should document why something happens but not what or how. code documents what is happening.
-----Original Message----- From: Alain Ravet [mailto:[EMAIL PROTECTED]] Sent: Friday, March 29, 2002 8:51 AM To: [EMAIL PROTECTED] Subject: Re: [Eap-features] Method contents popup windown Scaringi, Stephen wrote: > Yikes, don't document your code?! That has nothing to do with XP. Comments is not the only way to document code : - rename - extract method - introduce variable Are much more powerfull, and always in sync: before // valid zip code is between 1000 and 9999 if (1000 < code && code < 9999) { // handle valid zip code ... } else { .. } Let's remove the comments after boolean zicCodeIsValid = ((1000 < zipCode) && (zipcode < 9999)); if (zipCodeIsValid) { handleValidZipCode () ; } else { handleInvalidZipCode (); } When you work that way, you don't use/need many comments. And when you use them, the reader will know they are important. BTW: did you notice the mistake in the comment (between 1001 && 9998) => comments can be out of sync, without your noticing. Code cannot. > I hope I don't have to maintain your code in the future ;-) If you don't work that way, I hope 'I' won't have to maintain your code in the future. :-) Alain > Wouldn't it be much easier just to go to the method declaration (ctrl + B), rather than try to view the code in a little pop up window? > > In any case, I wouldn't want to see time spent on this since it's already implemented as "Go to | GotoDeclaration" and "Go to | Back". > > -Stephen > > -----Original Message----- > From: Erik Hanson [mailto:[EMAIL PROTECTED]] > Sent: Thursday, March 28, 2002 5:57 PM > To: [EMAIL PROTECTED] > Subject: [Eap-features] Method contents popup window > > > Trying to follow XP practices to the extreme, I've been trying to let the code > of my methods be the documentation, so I haven't been creating JavaDoc > comments for my methods (except for public API methods). > > IDEA's very cool JavaDoc popup (ctrl-Q) feature therefore doesn't help me as > much as it might help other people. It would be cool if IDEA provided a method > contents popup (ctrl-alt-Q or something) that would show the contents of > selected method in the same kind of popup box. If the method was bigger than > the box, the box could scroll or the contents could be truncated (maybe > truncation would force the programmer to make smaller methods). > > > (In case anyone is wondering, the argument against JavaDoc comments is that if > you don't change the comments when you change the code, you then have a worse > situation (incorrect comments) than you'd have if you didn't provide any > comments. I haven't decided if I agree with it, but I thought I'd try it out > for a while.) _______________________________________________ Eap-features mailing list [EMAIL PROTECTED] http://www.intellij.com/mailman/listinfo/eap-features _______________________________________________ Eap-features mailing list [EMAIL PROTECTED] http://www.intellij.com/mailman/listinfo/eap-features
