It should *always* be the simplest thing that could possibly work, my experience is that the bit in doubt is often the definition of "work" in question, especially if that definition has evolved over time.
For example, "working" could include the need to handle malformed data, or backwards compatibility, or not fixing and old bug that downstream users came to rely on, or working around a bug in some underlying component, or some strict performance requirements. In which cases the simplest thing might not be so simple. So when there's room for doubt, document exactly what working means - WHY a piece of code is there, HOW it's expected to be used. If you can't cleanly express a usage pattern through types and a DSL, then Javadocs and test fixtures are very often my favourite way to do this :) On 15 Apr 2013 07:39, "Bruce Chapman" <[email protected]> wrote: > If what we write first is "the simplist thing that might work", then I'd > suggest comments should explain code that is not apparently the "the > simplist thing that might work". or "comments should explain why the > simplistic thing that might have worked, didn't" > > > And on regular expressions - the minimum comment should include at least > one example of the "line" being matched against. It makes a huge > improvement to the grokkability of a regex if you can see an example of > what is being searched. > > > Bruce > > On 15/04/2013 8:50 a.m., Cédric Beust ♔ wrote: > > > On Sun, Apr 14, 2013 at 12:56 PM, Kirk Pepperdine < > [email protected]> wrote: > >> Though it pains me... I have to agree with you Cedric ;-) > > > Yeah sorry, I can't have that. > > I totally reverse my position on the subject. > > -- > Cédric > > -- > You received this message because you are subscribed to the Google Groups > "Java Posse" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > Visit this group at http://groups.google.com/group/javaposse?hl=en. > For more options, visit https://groups.google.com/groups/opt_out. > > > > > -- > You received this message because you are subscribed to the Google Groups > "Java Posse" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > Visit this group at http://groups.google.com/group/javaposse?hl=en. > For more options, visit https://groups.google.com/groups/opt_out. > > > -- You received this message because you are subscribed to the Google Groups "Java Posse" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/javaposse?hl=en. For more options, visit https://groups.google.com/groups/opt_out.
