E
Ed Kirwan
Hi, folks,
Does anyone know of a, "Standard," way to document software?
Perhaps I'm a dinosaur, but I find a text description is the easiest way
to start understanding code. This text description will ideally explain
the overall system and perhaps some key issues (concurrency, why certain
design decisions were made, etc.) in a few pages (say, less than 30);
after this, I find sequence diagrams (and to a lesser extent, use case
scenarios) to be the next useful way to see more detail.
I find class diagrams to be more of a reference than a self-contained
means of understanding a system's behaviour.
As far as I know, Rational's 4+1 view is a relatively widely-accepted
means of describing a system (architecture); though this tends, I find,
to go straight into the details rather than giving that 30-page overview
previously mentioned.
Of course, there's always Javadocs; but again, these are pretty
detailed, and as far as I'm aware there's no natural place to put a
system overview (I think there highest level descriptions are
package-level, though I haven't checked in a while). And in any case,
objects should never describe who their users are (they should never
care), so code comments tend to describe objects more or less in
isolation: great for API users, not so great as a starting point for
understanding a system.
(JavaHelp is for system users; I've not seen an example of JavaHelp
explaining system behaviour.)
Perhaps I'm just stuck in the past, and am too familiar with text
overviews to appreciate that such overviews are more well-suited to use
cases (or some such other documentary means). So how about a follow-up
question: does anyone know of any good program descriptions on the web?
I've googled for, amongst others, "Program description," and, "Program
documentation," but haven't come up with anything illuminating.
(Of course, many will say, "The code is the documentation;" to these I
say, "Here's 100,000 lines of code, prepare a summary of behaviour in 24
hours," and compare their conclusions with someone who has read a
30-page text overview.)
Tack så mycket ...
Does anyone know of a, "Standard," way to document software?
Perhaps I'm a dinosaur, but I find a text description is the easiest way
to start understanding code. This text description will ideally explain
the overall system and perhaps some key issues (concurrency, why certain
design decisions were made, etc.) in a few pages (say, less than 30);
after this, I find sequence diagrams (and to a lesser extent, use case
scenarios) to be the next useful way to see more detail.
I find class diagrams to be more of a reference than a self-contained
means of understanding a system's behaviour.
As far as I know, Rational's 4+1 view is a relatively widely-accepted
means of describing a system (architecture); though this tends, I find,
to go straight into the details rather than giving that 30-page overview
previously mentioned.
Of course, there's always Javadocs; but again, these are pretty
detailed, and as far as I'm aware there's no natural place to put a
system overview (I think there highest level descriptions are
package-level, though I haven't checked in a while). And in any case,
objects should never describe who their users are (they should never
care), so code comments tend to describe objects more or less in
isolation: great for API users, not so great as a starting point for
understanding a system.
(JavaHelp is for system users; I've not seen an example of JavaHelp
explaining system behaviour.)
Perhaps I'm just stuck in the past, and am too familiar with text
overviews to appreciate that such overviews are more well-suited to use
cases (or some such other documentary means). So how about a follow-up
question: does anyone know of any good program descriptions on the web?
I've googled for, amongst others, "Program description," and, "Program
documentation," but haven't come up with anything illuminating.
(Of course, many will say, "The code is the documentation;" to these I
say, "Here's 100,000 lines of code, prepare a summary of behaviour in 24
hours," and compare their conclusions with someone who has read a
30-page text overview.)
Tack så mycket ...