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 -~----------~----~----~----~------~----~------~--~---
