on Tue, Feb 07, 2006 at 05:12:57PM +0000, Magnus Therning (magnus@therning.org) wrote:
> Maybe someone else has stumbled on this, either as a plugin to an editor
> or as a stand-alone tool :-)
>
> I do a fair bit of code auditing, and while trying to make sense of
> other people's mess I take notes. So far I've done this in vi (my editor
> of choice), but this means I always have to document where the code I'm
> commenting is (location, filename, line number, function name, etc).
> It'd be so much nicer if I could do the commenting right "in the
> source". I've been looking for a tool that would "interleave" the
> original source and my comments. Never modifying the source by saving my
> comments separately (but still associating the comments with the source
> in some way). Is there such a tool already?
Not something I've had much direct experience with, but this sounds
suspiciously close to Donald Knuth's "Literate Programming". Which may
be more an ideal than something useful, but might make a good starting
point in your search.
http://www-cs-faculty.stanford.edu/~knuth/lp.html
Literate Programming
by Donald E. Knuth (Stanford, California: Center for the Study of
Language and Information, 1992), xvi+368pp.
(CSLI Lecture Notes, no. 27.)
ISBN 0-937073-80-6
Japanese translation by Makoto Arisawa, Bungeiteki Programming
(Tokyo: ASCII Corporation, 1994), 463pp.
Literate programming is a methodology that combines a programming
language with a documentation language, thereby making programs more
robust, more portable, more easily maintained, and arguably more fun
to write than programs that are written only in a high-level
language. The main idea is to treat a program as a piece of
literature, addressed to human beings rather than to a computer. The
program is also viewed as a hypertext document, rather like the
World Wide Web. (Indeed, I used the word WEB for this purpose long
before CERN grabbed it!) This book is an anthology of essays
including my early papers on related topics such as structured
programming, as well as the article in The Computer Journal that
launched Literate Programming itself. The articles have been
revised, extended, and brought up to date.
See also:
http://www.literateprogramming.com/
http://vasc.ri.cmu.edu/old_help/Programming/Literate/literate.html
Peace.
--
Karsten M. Self <kmself@ix.netcom.com> http://kmself.home.netcom.com/
What Part of "Gestalt" don't you understand?
gconf-editor: reimplementation of the MS Windows Registry for
GNU/Linux, with the concommitant problems of undocumented settings,
cryptic keys, inability to comment settings, and use of a single,
specialized application to access the configuration settings.
- Karsten M. Self
Attachment:
signature.asc
Description: Digital signature