On 10-Apr-09, at 08:54 , julius wrote:
Hi,
is there any way of including diagrams within the comments of my
source code (Objective-C in XCode 3.1.2.)?
Let me thank everybody for the great response I got for my then seemingly simple question.
I now have what looks like a simple XCode solution.
It is strange but I had lived a good part of my programming life firm in the belief that the ability to include images in one's code would make writing and understanding code considerably easier. I still remember one of my first teachers of computing showing us how, in Cobol, wholly in spirit with the delights of JavE ( http://www.jave.de/) to use the ascii character set to draw little boxes representing modules and the connections between them.
Having had time to think about things I finally came up with what I think might be a good XCode solution. This has come from my having revised my belief: not with respect to the utility of images but with respect to including them in the source code. It is easy to conceive of situations where a small image would be useful. For instance, think of the usefulness of occasionally being able to see a properly laid out mathematical formula of immediate relevance to the next 15 lines of code. I'm thinking of a formula a la Latex: http://www.latex-project.org/ or its sitmo incarnation http://www.sitmo.com/latex/. However, this idilic view does not in my current opinion transfer to situations where the image needs to be bigger, or where quite a few diagrams are needed, or where the referencing code runs to more than a few lines. Think how irritating it would be to have the images scrolling up out of sight as one works one's way through the source code. Split windows would just annoy further. Thinking about this makes it immediately obvious why the editor code needed to support such a facility could take on the characteristics of bloat. And what if it were also to support the frequently needed task of editing the images? Nasty.
My original approach to this problem prior to making the original posting was to draw my diagrams in Intaglio ( http://www.purgatorydesign.com/Intaglio/) and print them out so I had them beside me as I wrote the code, or I'd just display them on screen. Finding them in the file system was relatively easy when displayed as really big icons. But I have lots of images and lots of updates and it got messy. I then started saving the images as png and including them in a set of indexed html pages. I could look through the index to find the images and have these open in the browser whilst editing in the XCode windows beside them.
There are several problems with this approach. First is the question of indexing the html pages and of how to point the reader of the source code at the html. I hate having actual links in the code - they're not only a distracting shocking blue but a nightmare to edit because do it wrong and there's web pages opening up all around you. If you don't use links but names or refences then these change quite quickly and are a pain to keep meaningful and up to date, as are the images themselves. As I work on the code I'm forever changing the way I do things. So I then need to go into the file system, dig out the original intaglio files (I can't display these in the browser) make the mods, save as png then move the png into the appropriate folder: a real nuisance. Moreover, since I became an "extreme programmer" ( http://www.extremeprogramming.org) I find taking measurements directly from images a very good way of generating Unit Test data for my heavily graphics based programs ( http://developer.apple.com/mac/articles/tools/unittestingwithxcode3.html). This has dramatically increased my need to keep images closely tied in to the code. Similar considerations discouraged me from using Doxygen http://www.stack.nl/~dimitri/doxygen.
So here's my current solution. I'm sure that to many of you it will be like teaching grandma to suck eggs but I include it for the less-XCode-savvy like myself. When I have a set of images and perhaps some text files that need to be associated with one or more source files I create an XCode group, put the source into it and then import all my diagramatic stuff into the group using "add to project". This works quite well. The grouping obviates the need for any links to the diagrams in the code since it is quite obvious what goes with what. I can use intaglio files directly and edit these in place. I can have a whole number of windows open, position them as I want when I want, resize the images with zoom etc. Different versions of the images get saved with the different versions of the program (I've had problems with getting SCM to work properly and having spent more than a year getting to grips with Cocoa just can't afford more time on learning curves so I version manually by duplicating the whole project and adding a date to the copy).
So there it is. I've been using this approach for a few days now seemingly without incident. If there is one drawback it is that the file structure displayed by XCode, namely of the Groups which are represented by folder like icons, is not replicated in the file system itself, so if one wants things to be grouped in the file system as well as in XCode one needs to do this by putting a suitable prefix to the filenames. I do this normally but including this additional grouping adds to the overhead.
So I thank's again to everyone. Best wishes Julius
|