Re: patch applied (packages/base): Inline Data.Bits.rotate <at> Int, enables rotate to be constant folded
Don Stewart <dons <at> galois.com>
2008-05-02 16:23:34 GMT
> Great stuff Don,
> I've learned from experience that in 2 yrs time I will have forgotten
> why that INLINE is there, and may remove it. (Probably not in this
> particular case, but something similar.) You may think that the info
> is in the commit message, but in practice I just don't do a darcs
> annotate to see which patches modified the line, and look at the
> commit log.
> I think it's better to invest effort in putting documentation in the
> source code. Rather than clutter up the (Bits Int) instance, nowadays
> I add -- See Note [Constant folding for rotate] and put a block
> comment, headed by that same string, lower down in the file.
I like this idea.
> I have found that this is a robust and effective way of documenting
> things. Does that make sense?
> I've pushed a patch doing this to Data.Bits.
> Maybe I should update the programming conventions wiki!
Yep, that might be a good idea. Something about providing good text,
with reproducible examples, and then adding that text as a footnote in