Re: Storing notes/thoughts about code in Xcode and in the code
Re: Storing notes/thoughts about code in Xcode and in the code
- Subject: Re: Storing notes/thoughts about code in Xcode and in the code
- From: Greg Guerin <email@hidden>
- Date: Tue, 12 Sep 2006 19:55:58 -0700
Bjoern Knafla wrote:
>On the other hand I would also like to use this system to hold notes why I
>choose a specific design or why not - and it would be great if these infos
>would be put into a version revision system and I would be able to browse
>through the old versions of the notes and the "current" version without
>having to switch the code file revision itself.
Just create design notes in separate files. If you wish, you can give them
a uniform suffix, like ".dnote", or incorporate a uniform pattern in the
name, such as always having the word "notes" before the suffix (i.e. the
globbing pattern "notes.*").
I've been writing design notes like this for years. They've always been
informal, as I work out design issues, explore tradeoffs, and so on. In
olden days I used Acta (an outliner), but had problems exchanging those
files across platforms. Then I started using plain text in plain ordinary
text files. Lately, I've been writing them in plain text augmented by
Markdown (a lightweight markup language). Markdown makes it easy to
convert them into HTML and publish them where others can browse them, but
the Markdown codes are simple enough you can write and edit it without all
the fiddliness of HTML. For more info, search Wikipedia for Markdown.
When I write code after creating design notes, I often write comments that
say "Refer to section 'Xyzzy' of file 'Foo design notes' for the
rationale." Sometimes the rationale is as much about what won't work and
why as it is about the particular design I've chosen.
Whether HTML, plain text, or anything else, these notes are always informal
design notes, as distinct from a design spec or other formal design docs.
Still, when someone asks "What's your thinking about Xyzzy?" I can refer to
them with ease. And although informal, they are managed and versioned
along with other files.
If you're waiting for a cool Xcode feature to get you started writing design
notes, forget it. The cool feature won't improve your design
documentation. Nor is it likely to motivate you to write design notes,
except briefly. The difficult part is the discipline to consistently write
meaningful design notes, and no cool feature will give you that.
-- GG
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Xcode-users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden