At that point, the source code often becomes unreadable. At least, for me. Personally, I need the code to be more or less intact, rather than balkanized. What I think needs to happen is something similar to MS Word's comments view (where various people's comments are stored in the doc file, but are displayed as marginalia). An IDE could interpret either an external file, or some extended comment block, and pull that away from the main part of the source, so that it is still intact, but the callouts are still accessible. It still doesn't address "Why are visitors a good way to transform ASTs?", or the like. Instead, it's still focussed on the particular implementation, and thus can easily become desynchronized. It's the more general "How do you build a compiler, and why are certain tradeoffs made?" that I think the OP was asking about. Something too broad of scope to be good comment fodder, IMHO. "Read the source" then becomes a non-answer.
________________________________ From: [EMAIL PROTECTED] on behalf of Joshua Kugler Sent: Wed 3/1/2006 10:09 AM To: [email protected] Subject: Re: [IronPython] CLS compliance On Tuesday 28 February 2006 22:08, Keith J. Farmer wrote: > > Well, you can read the complete source code of IronPython. > > > > Yes, it uses reflection to consume CLS types. > <soapbox> > Source code and API listings are merely implementation details; they > generally do a poor job of explaining why a thing is done a certain way, > and so are of limited scope in education. > </soapbox> <soapbox type="reply"> Properly (even heavily) commented source *should* explain why things are done a certain way. They should go beyond simple things like, "Check to make sure we're not over some limit." If the source code is to be understandable to newbies (or even new hires), comments should fully explain architecture, design decisions, and code flow. Of course, I've yet to run into a project that does this well. Hopefully, a couple of my upcoming projects at work will have more comments than source code. :) </soapbox> j----- k----- -- Joshua Kugler PGP Key: http://pgp.mit.edu/ CDE System Administrator ID 0xDB26D7CE http://distance.uaf.edu/ _______________________________________________ users mailing list [email protected] http://lists.ironpython.com/listinfo.cgi/users-ironpython.com _______________________________________________ users mailing list [email protected] http://lists.ironpython.com/listinfo.cgi/users-ironpython.com
