I agree. If code requires comments then perhaps the symbols need renaming or the code could do with a clean up. But I do expect and hope to find comments that explain business rules that couldn't possibly be inferred from the code. Even if you can see what it's doing, sometime you need to know why.
On Apr 14, 8:11 am, Peter Becker <[email protected]> wrote: > Alexey Zinger wrote: > > --- On Sun, 4/12/09, Peter Becker <[email protected]> wrote: > > >> From: Peter Becker <[email protected]> > >> Subject: [The Java Posse] Re: Code definition > >> To: [email protected] > >> Date: Sunday, April 12, 2009, 1:12 AM > >> Alexey Zinger wrote: > > >>> --- On Fri, 4/10/09, Dominic Mitchell > > >> <[email protected]> wrote: > > >>>> From: Dominic Mitchell > > >> <[email protected]> > > >>>> Subject: [The Java Posse] Re: Code definition > >>>> To: [email protected] > >>>> Date: Friday, April 10, 2009, 11:35 AM > >>>> On Fri, Apr 10, 2009 at 10:20:32AM -0400, Robert > > >> Hanson > > >>>> wrote: > > >>>>> Every Perl program I have ever written falls > > >> into that > > >>>> category. Six > > >>>>> months later I can't even figure out how > > >> it works. > > >>>> Believe me, Perl isn't unique in that > > >> category. > > >>>> There's a *lot* of > >>>> really incomprehensible Java out there. Sure the > >>>> individual lines might > >>>> be readable (if you're lucky) but the program > > >> as a > > >>>> whole is unreal. > > >>>> -Dom > > >>> Unless I'm in a real time crunch, I try to step > > >> back after getting the first working version of something > >> and look over what I just wrote. If I see something > >> that's gonna be confusing later (weird work-arounds, > >> subtle diversions from familiar patterns or conventions, or > >> techniques I use very rarely), I simply write comments. > >> I've found certain things to come up time and again that > >> require explanation, where the source is not expressive > >> enough for a casual code reader. Regular expressions are a > >> common case, especially in Perl, where they are often not > >> accompanied by expressive variable names (99% of the time a > >> good example of what you're trying to match does the > >> trick). In Java, I've lately found some hidden traps in > >> using GWT, where what looks like good Java will break or > >> have unexpected behavior or performance. Comments are your > >> friend. > > >> It sounds like the type of comment I consider a code smell. > >> If you need > >> to explain what your code does it might be time to refactor > >> the code > >> into something legible. Of course there are exceptions, > >> e.g. if you need > >> some stunts for that last bit of performance (assuming you > >> need that > >> last bit of performance in the first place), but in most > >> cases I get > >> suspicious if I see code with a lot of inline comments. > > >> But I guess to some extent it is a matter of style and also > >> how much you > >> are allowed to dig in and change the whole code to > >> something different. > > >> Peter > > > Call it what you wish, but I think of it as a situation, where I am taking > > a step in the direction of obscurity for some specific reason (to me, it's > > not always a bad reason) and compensate for it with clear and concise > > comments. I think it's just realistic -- you can't expect every single API > > or your own line of code to be completely self explanatory. It's just a > > fact of life. I just looked up some regex examples and came across this: > > (19|20)\d\d[- /.](0[1-9]|1[012])[- /.](0[1-9]|[12][0-9]|3[01]) > > Would you prefer to see this in your code with no explanation, or a little > > line that tells you it's a date matching pattern, or better still, gives > > you a pseudo pattern or an example of what's expected to match? > > As I said: there are exceptions. Although in this case I'd much prefer a > nicely named constant with some JavaDoc explaining the RegExp in the > detail necessary. A similar thing can be true for calculations: I > personally rather have a method with just a complicated return statement > and some JavaDoc than the inline comments. It binds things better > together and causes less distraction when reading the code. > > But these things are a matter of taste to (quite) some extent. I > probably tend to overreact a bit since I have seen the "Just Add > Comments" antipattern too often. People would add comments to explain > their code where it would have been much easier to refactor. And a year > later the comments are outdated. > > But yes: your example is certainly something that needs some type of > documentation unless you can be sure everyone reading it will be a > RegExp wizard. The alternative would be avoiding it: it would still let > you declare the 31st of February anyway, so you'll need validation > beyond that or an even more complicated pattern. > > Peter --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "The Java Posse" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/javaposse?hl=en -~----------~----~----~----~------~----~------~--~---
