Re: [gobo-eiffel-develop] bridge pattern and feature comments

[Eric B. <er...@go...>]

Andreas Leitner wrote:
> 
> Now I wanted to start working on the documentation of the various
> implementations. But I remember the in the book "The Pragmatic
> Programmer" they talk about too much documentation, documentation
> that is redundant that is. They argue that such documentation is
> likely to get out of sync and thus it is better to not introduce
> redundant documentation in the first place.
> 
> What is your (the list, or better Eric :) opinion on that?

I don't exactly remember what "The Pragmatic Progammer" says,
but I guess it's something like the doc in the source code gets
out of sync with the paper/HTML doc. Here it is different: the
header comment documents the routine. If you have two similar
routines it's normal that you end up with two similar header
comments. It's unlikely (although possible) that the header
comment gets out of sync with the body of its routine, however
it would be very painful if we would have to go to a similar
routine in another class in order to read the header comment of
a given routine. So I don't think that the header comments are
redundant in this case. It's as if you wouldn't put the header
comment in a redefined routine just because it already appears
in the ancestor class. I don't think that flat-tools are
currently able to display the inherited header comment (they
usually display the header comment of the redefined version
of the routine), therefore the header comment should be repeated
(and possibly improved) for ease of reference. I think we should
do the same in your case for the bridge pattern.

-- 
Eric Bezault
mailto:er...@go...
http://www.gobosoft.com