[Squeakfoundation]The Harvesting process and the BFAV

[goran.krampe at bluefish.se]

"Andreas Raab" <andreas.raab at gmx.de> wrote:
> Hi Göran,
> 
> > > Err ... actually this is wrong. Really, we never intended 
> > > to "write comments later".
> > 
> > True. You probably didn't think like I wrote it. I take that back!
> > And you probably had your reasons - you didn't intend to go open 
> > source etc, it was your own "box" and it was of course all up to
> > you how you worked etc. I didn't imply any blame. :-)
> 
> I didn't read any in your message ;-) I just wanted to point out that your

Good. :)

> logical conclusions have a wrong premise. And as you all know logic teaches
> us that starting from a wrong premise we can come to any conclusion we want
> ;-)

True, I took it back.
 
> > But nevertheless the net effect is the same unfortunately - 
> > and I don't think we should go on doing the same mistake.
> 
> That's (where I think) you are wrong. At least if by "doing the same
> mistake" you mean to "intend to write comments later". We never intended
> that.

Ok, let me rephrase it then: "Let's not continue putting uncommented
code into the image as was done previously.".

I just don't care about the reasons - but if you ask me (you don't but I
pretend you do :-) ) personally I still think it was a pretty dumb move.
In my experience taking the decision to not take the time to write
"proper comments" always bites back sometime in the future. And as you
can see - even though you couldn't possibly predict the windling road of
Squeak - it bit back this time too.
 
> > If anyone disagrees with this I am all ears, please tell me
> > why it would be good to insert uncommented code into Squeak.
> 
> It isn't good - in my understanding it is simply unavoidable in various
> areas if you have an incrementally developing system. Personally, I have
> found that if I "write comments first" they almost always end up wrong as at
> this time I can't cover the workings of a certain class in detail yet. So it
> is very likely that I decide to do some things differently somewhere down
> the line and then the (early) comment ends up wrongly. If I want _accurate_
> comments I always write them after the fact.

Sure, now we are talking about the varius states during development.
Fine, different developers work differently. But nevertheless there
comes a point in development when the code you write suddenly becomes
the code *I read*. In a team that point in time can come quickly - right
after you commit it to our shared repo. In open source it comes after
first public release.

It is *at that point* that I think the code should include comments. And
I find it amazing that I need to argue for this! Come on people! XP sure
is nice, but when people use those ideas to simply "get away from
needing to explain things to others", I get annoyed.

> Incidentally, this is one of the major differences I see with respect to
> comments vs. tests. Tests are kept pretty much "automatically in sync" with
> the actual code so (for example) as far as boundary conditions go tests
> document the code much better than any comment could. This is not true for
> overall design issues (at which tests are horrible) but for many situations
> a test can be (at least) as helpful as a comment.

I agree - and if you read about my "Magic Book" ideas you know that I
would like to leverage that fact even more.

But... :-) I *still* think proper simple comments is something that
should be written! Hey, call me old-fashioned.

> Cheers,
>  - Andreas

Cheers, Göran