Very good point. I notice this difference a lot in commit messages: 
quite often they are written in a way that is entirely redundant with 
the diff you get. That might make sense for large commits (kind of like 
an executive summary), but I've seen micro-commits with messages written 
that way. What I'd really like to read is an answer to the question "why 
did you change this?", I can see what has changed much more accurately 
in the diff. Unfortunately most people tend to document the What, but 
not the Why. I'm not sure if that's part of human nature or just a 
(sub-)cultural thing.

BTW: another great thing to document is what didn't work. That's actual 
a good one in terms of inline comments: "DO NOT use X here, since that 
would break for the following reason...". Inline comments are not all 
bad, just overused.

   Peter


Steven Herod wrote:
> What the code does can always be understood. It may not be easy, and
> you may not enjoy it. But you can figure it out eventually.
>
> Why however is the real problem.  That's where the comments matter.
>
> I'd rather dirty code with comment about business intent and great
> code with no 'why'
>
> On Apr 13, 8:47 pm, Christian Catchpole <[email protected]>
> wrote:
>   
>> 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
-~----------~----~----~----~------~----~------~--~---

Reply via email to