Re: Lines of documentation per LOC

Re: Lines of documentation per LOC

[Robert I. Eachus]

In article <1994Oct25.170005.27711@sei.cmu.edu> lpb@sei.cmu.edu (Loic Briand) writes:

 > Is there any document or source of information that provides
 > an accepted (?) ratio (lines of documentation / lines of code) for a 
 > software design document (SDD)?
 > Talking with people around me, I got values between 10 and 0.1, 
 > but no rationale other than: "the description has to be complete and
 > sufficient to allow modifications" and stuff like that.

   At first I couldn't believe that this was posted by someone at the
SEI.  Then I noticed it was posted by an industrial affiliate, who may
learn something while he is there.  And on second reading, I realized
he had gotten the right answers and dismissed them!  Maybe he won't
learn after all.

   The right amount of documentation is a function of the code!  I
have written pages of doumentation for a dozen line package.  I have
also written code with very sparse documentation--in some cases just a
mathematical sequence and its source.  Anyone looking for magic
numbers in this area is doomed to be frustrated.  Anyone working
for him is probably going to be damned to a Procrustean bed.
--

					Robert I. Eachus

with Standard_Disclaimer;
use  Standard_Disclaimer;
function Message (Text: in Clever_Ideas) return Better_Ideas is...

Lines of documentation per LOC

[Loic Briand]

Is there any document or source of information that provides
an accepted (?) ratio (lines of documentation / lines of code) for a 
software design document (SDD)?
Talking with people around me, I got values between 10 and 0.1, 
but no rationale other than: "the description has to be complete and
sufficient to allow modifications" and stuff like that.



---------------------------------------------------------------------------
--  O p i n i o n s   e x p r e s s e d   h e r e   a r e   m y   o w n  -- 
--  Loic Briand  SEI Resident Affiliate  lpb@sei.cmu.edu  (412) 268-6674 --
--  Sponsored by Wilcox Electric/Thomson-CSF           briand@wilcox.com --

Re: Lines of documentation per LOC

[Loic Briand]

In article <EACHUS.94Oct25190056@spectre.mitre.org>, eachus@spectre.mitre.org (Robert I. Eachus) writes:
|> In article <1994Oct25.170005.27711@sei.cmu.edu> lpb@sei.cmu.edu (Loic Briand) writes:
|> 
|>  > Is there any document or source of information that provides
|>  > an accepted (?) ratio (lines of documentation / lines of code) for a 
|>  > software design document (SDD)?
|>  > Talking with people around me, I got values between 10 and 0.1, 
|>  > but no rationale other than: "the description has to be complete and
|>  > sufficient to allow modifications" and stuff like that.
|> 
|>    At first I couldn't believe that this was posted by someone at the
|> SEI.  Then I noticed it was posted by an industrial affiliate, who may
|> learn something while he is there.  And on second reading, I realized
|> he had gotten the right answers and dismissed them!  Maybe he won't
|> learn after all.
|> 
|>    The right amount of documentation is a function of the code!  I

Robert, I am not totally stupid. I _know_ that the amount of documentation is
function of the code.  The problem is that when you have a client who ask for
10 lines of doc par LOC and you have budgeted 0.1 (based on the expected
complexity of your code), you have to prove your point.
All you can do is look for data, books, articles, and other material
possibly writen by people who know what they are talking about.

Lets clarify for you what I am looking for: data-based statistical ranges like:

Embedded Real time program, Ada
 . Complex algorithm:           10 to 20 lines of doc / LOC
 . Intermediate complexity:    0.6 to 9 
 . Simple sequential program:  0.1 to 0.5
Accounting program, Cobol
 . Complex algorithm:           10 to 25 lines of doc / LOC
 . Intermediate complexity:      4 to 9 
 . Simple sequential program:    1 to 3

Then if you estimate that 10% of your code is complex, 55% intermediate, and
the rest simple, you can predict a documentation effort, based on _data_.

|> have written pages of doumentation for a dozen line package.  I have
|> also written code with very sparse documentation--in some cases just a
|> mathematical sequence and its source.  Anyone looking for magic
|> numbers in this area is doomed to be frustrated.  

It is not about magic numbers, it is about _measuring_.
Documenting a design is not an activity fundamentally different of designing
or coding. A lot of attention is given to the predictability of the design or
coding time. The same attention should be given to the documentation time. 

I suppose you know that it is impossible to predict any duration without
reference data. So, tell me: how do you budget/plan the documentation of a
program? (Note: I am not talking about a package written in my kitchen, but
of something larger, say, 1 million LOC). Do you use data recorded on
previous developments of similar complexity? So there are existing data? 
So may be somebody published something? Guess what: it is what I am looking
for. 

If people like Capers Jones published data saying things like "the detailed
design productivity in function points per staff month ranges from 25 to 300
(median: 150)", I don't see any reason why there would not be relevant
data published on the design documentation.

And BTW, I am learning a lot at SEI. Great place for a resident affiliate.

|>                                                   Anyone working
|> for him is probably going to be damned to a Procrustean bed.
|> --
|> 
|> 					Robert I. Eachus
|> 
|> with Standard_Disclaimer;
|> use  Standard_Disclaimer;
|> function Message (Text: in Clever_Ideas) return Better_Ideas is...
.


---------------------------------------------------------------------------
--  O p i n i o n s   e x p r e s s e d   h e r e   a r e   m y   o w n  -- 
--  Loic Briand  SEI Resident Affiliate  lpb@sei.cmu.edu  (412) 268-6674 --
--  Sponsored by Wilcox Electric/Thomson-CSF           briand@wilcox.com --

Re: Lines of documentation per LOC

[Robert Firth]

In article <1994Oct26.094543.24213@sei.cmu.edu> lpb@sei.cmu.edu (Loic Briand) writes:

>Robert, I am not totally stupid. I _know_ that the amount of documentation is
>function of the code.  The problem is that when you have a client who ask for
>10 lines of doc par LOC and you have budgeted 0.1 (based on the expected
>complexity of your code), you have to prove your point.

Suggestion: write a code reformatting tool that will copy Ada code
and join or split lines of comment to meet any required comment
density.  Then write the code and comment it properly.  Then use
the formatting tool to give you the number of lines of comment
you need.

The best weapon against the ridiculous is ridicule.  Always will be.

Re: Lines of documentation per LOC

[Robert Dewar]

what possible bizarre thinking leads to the conclusion that COBOL requires
ten times the density of comments as Ada for simple sequential
algorithms ...

Re: Lines of documentation per LOC

[Norman H. Cohen]

In article <1994Oct26.094543.24213@sei.cmu.edu>, lpb@sei.cmu.edu (Loic
Briand) writes: 

|>                        The problem is that when you have a client who ask for
|> 10 lines of doc par LOC and you have budgeted 0.1 (based on the expected
|> complexity of your code), you have to prove your point.

What idiocy!  This is a fine incentive to start writing Ada code like

for I in L'Range(1)loop for J in R'Range(2)loop Res(I,J):=0.0; for K in
L'Range(2)loop Res(I,J):=Res(I,J)+L(I,K)*R(K,J);end loop;end loop;end loop;

instead of

   for I in Left'Range(1) loop
      for J in Right'Range(2) loop
         Result(I, J) := 0.0;
         for K in Left'Range(2) loop
            Result(I, J) :=  Result(I, J) + Left(I, K) * Right(K, J);
         end loop;
      end loop;
   end loop;

-- (unless,
-- of
-- course,
-- you
-- write
-- your
-- comments
-- like
-- this).

--
Norman H. Cohen    ncohen@watson.ibm.com

Re: Lines of documentation per LOC

[mat]

In article <EACHUS.94Oct25190056@spectre.mitre.org>, eachus@spectre.mitre.org (Robert I. Eachus) writes:
> In article <1994Oct25.170005.27711@sei.cmu.edu> lpb@sei.cmu.edu (Loic Briand) writes:
> 
>  > Is there any document or source of information that provides
>  > an accepted (?) ratio (lines of documentation / lines of code) for a 
>  > software design document (SDD)?
>  > Talking with people around me, I got values between 10 and 0.1, 
>  > but no rationale other than: "the description has to be complete and
>  > sufficient to allow modifications" and stuff like that.
> 
>    At first I couldn't believe that this was posted by someone at the
> SEI.  Then I noticed it was posted by an industrial affiliate, who may
> learn something while he is there.  And on second reading, I realized
> he had gotten the right answers and dismissed them!  Maybe he won't
> learn after all.

If the original poster will look carefully at the `stuff like that,' I
belief he will find all the criteria he needs to determine whether
the design documents will meet their needs.  He has, in other words, a
specification for design documents.

His job is now to determine what design documents will meet that spec.

He's looking for another spec, one that doesn't require him to think,
one that doesn't require him to expend engineering effort on every step
of the engineering process.

It don't work that way.

If you get a set of criteria that tell you how to judge your work against
the real needs it must meet, treasure them.  Paint them on your walls,
and repeat them in chant as you enter and leave the office.  Begin every
design document with page on which those criteria are written.

Cherish and apply the wisdom you receive.

Or read Schwartzkopf's book, and particularly the section where he has
nailed down the five main responsibilities of mid-level army leadership
_and_ management.
-- 
 (This man's opinions are his own.)
 From mole-end				Mark Terribile
 mat@mole-end.matawan.nj.us, Somewhere in Matawan, NJ
	(Training and consulting in C, C++, UNIX, etc.)

Re: Lines of documentation per LOC

[mat]

In article <1994Oct26.094543.24213@sei.cmu.edu>, lpb@sei.cmu.edu (Loic Briand) writes:
> 
> In article <EACHUS.94Oct25190056@spectre.mitre.org>, eachus@spectre.mitre.org (Robert I. Eachus) writes:
> |> In article <1994Oct25.170005.27711@sei.cmu.edu> lpb@sei.cmu.edu (Loic Briand) writes:

Documenting _after_ the program is done is like drawing plans
after the building is built.

> |>  > Is there any document or source of information that provides
> |>  > an accepted (?) ratio (lines of documentation / lines of code) for a 
> |>  > software design document (SDD)?

A better question, I think, is `how many lines of code result from a line
of SDD?'

The SDD, after all, specifies the code, and not the other way around.

> Robert, I am not totally stupid. I _know_ that the amount of documentation is
> function of the code.  The problem is that when you have a client who ask for
> 10 lines of doc par LOC and you have budgeted 0.1 (based on the expected
> complexity of your code), you have to prove your point.

I'd start by explaining that you write the code _from_ the design documents,
not the other way around.

If the design documents are sufficient to specify working code, there
should be no question about whether it is complete enough for the code.
-- 
 (This man's opinions are his own.)
 From mole-end				Mark Terribile
 mat@mole-end.matawan.nj.us, Somewhere in Matawan, NJ
	(Training and consulting in C, C++, UNIX, etc.)

Re: Lines of documentation per LOC

[Loic Briand]

In article <1994Oct25.170005.27711@sei.cmu.edu> lpb@sei.cmu.edu (Loic Briand) writes:

 > Is there any document or source of information that provides
 > an accepted (?) ratio (lines of documentation / lines of code) for a 
 > software design document (SDD)?

I received quite a lot a flaming after this simple request. The usual
net gurus made their usual doctoral comments (talking on the net
makes some people amazingly arrogant). 

I finally got a few good references on the subject. They are by Capers Jones:

. His column "Software Challenges" in IEEE Computer (October 1994)
. His book "Assessment and Control of Software Risks" (Prentice Hall, 1994).

The statistics are in number of pages per function points. For the military
software, there is an average of 3.40 pages of spec/function point. (the total
amount of documentation is 6.15 pages/function point).
The article provides details on the relative amounts of user requirements,
functional specifications, logic specifications... Other domains (MIS,
commercial) are also analyzed.

An interesting point in the discussion is that organizations that are CMM level
3 could be subject to a reduction of paperwork, because "Much of the paperwork
required by the military standard 2167A has no particular relevance to the
technology of building or maintaining software. It was required primarily to
demonstrate that vendors knew what they were doing and were doing it on time -
that is, because DoD did not trust its vendors."

---------------------------------------------------------------------------
--  O p i n i o n s   e x p r e s s e d   h e r e   a r e   m y   o w n  -- 
--  Loic Briand  SEI Resident Affiliate  lpb@sei.cmu.edu  (412) 268-6674 --
--  Sponsored by Wilcox Electric/Thomson-CSF           briand@wilcox.com --