Re: [isabelle] unhelpful comment in Term.ML


Am Mittwoch, den 11.11.2015, 15:59 +0100 schrieb Makarius:
> A positive example is probably the Glasgow Haskell Compiler, see also
>Â;-- although I have never looked
> at the actual sources.

I have. The GHC sources are full of comments, and one of the main jobs
of Simon Peyton Jones these days seems to be to reply to people who
submit patches to fix bugs or implement new features: âMore Notes!â

The concept of Notes is worth describing: Simon has noticed that your
code get harder to read if it is too cluttered by inline comments â
after all, one huge benefit of functional code is its conciseness that
allows you to see more code at once.

OTOH, such code, even if written carefully, often does not explain
itself fully, in particular its interaction with other parts of the
system. So the question arises, where to add this information? Inline
comments are to be avoided if they are longer than a few words. But
stuff in wikis or user guides, or â worse â trac ticket, code reviews,
random READMES or mailing list, quickly goes out of sync with the code.

So the solution is to have Notes, which are extended comments (from a
few lines to several paragraphs), with examples, in the source file,
not within the code in question, but near it (e.g. the bottom of the
fie). They are then referenced from all relevant positions in the code
with, say "See NoteÂ[Asymmetry of 'both' for DmdType and DmdResult]".
This alerts everyone who touches an affected function that there is
something non-trivial and non-obvious about the code.

Also, whenever you make a small change to existing code, you are
encouraged to write a Note about it: Because if it were obvious, then
it would have been done like that in the first, place, wouldnât it?

A quick grep finds 1067 such Notes in GHCâs HEAD.

It still happens that I submit a patch which I think is obvious, and
yet Simon asks me to write a Note, and indeed: Often it would not have
been obvious to me any more after a few months. So all in all, I am
quite fond of this approach, and GHC ability to still evolve and to
take up new contributors shows its strength. But naturally, it needs to
be taken serious, with new contributors trained to follow this style.


Dipl.-Math. Dipl.-Inform. Joachim Breitner
Wissenschaftlicher Mitarbeiter

Attachment: signature.asc
Description: This is a digitally signed message part

This archive was generated by a fusion of Pipermail (Mailman edition) and MHonArc.