[ic] Re: [interchange-cvs] interchange - docelic modified 5 files

[Davor Ocelic]

On Wed, 29 Mar 2006 05:43:19 +0200
Andreas Grau <agrau at esquat.com> wrote:

> > --- qb_safe.filter	8 Nov 2005 18:14:32 -0000	1.6
> > +++ qb_safe.filter	27 Mar 2006 22:21:13 -0000	1.7
> > @@ -1,11 +1,7 @@
> >  # Copyright 2002-2005 Interchange Development Group (http://www.icdevgroup.org/)
> >  # Copyright 1996-2002 Red Hat, Inc.
> >  # Licensed under the GNU GPL v2. See file LICENSE for details.
> > -# $Id: qb_safe.filter,v 1.6 2005/11/08 18:14:32 jon Exp $
> > -
> > -# QuickBooks Safe: make data safe for quickbooks
> > -# QB will crash at the drop of a hat, so don't forget to remove 
> > -# any unfriendly characters.
> > +# $Id: qb_safe.filter,v 1.7 2006/03/27 22:21:13 docelic Exp $
> >  
> 
> What's wrong with the comment ?
> 
> On one side, people are recommended to read the code for clarity, on
> the other side valuable information is deleted.


I don't want to repeat myself. Nothing is wrong.

I didn't delete it, I moved it. (I wonder if I need to put this in
font size 100, red color, and make it <blink>).


At least one problem with comments in files is that, when you 
are looking at the documentation in xmldocs, you first read
the information in the proper place (under DESCRIPTION or NOTES
section), and then when you scroll down to see tag source code,
you see it in there again. There's nothing appealing or
value-adding in it.

And if you tried to use qb_safe (or anything else) without reading
the docs, and learn from a 3-line comment that 
"QB will crash at the drop of a hat", then you've got bigger
problems than documentation anyway.