[IronPython] comments vs docs (was RE: CLS compliance)

[Keith J. Farmer]

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: users-bounces at lists.ironpython.com on behalf of Joshua Kugler
Sent: Wed 3/1/2006 10:09 AM
To: users at lists.ironpython.com
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
users at lists.ironpython.com
http://lists.ironpython.com/listinfo.cgi/users-ironpython.com