From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=BAYES_00,INVALID_DATE autolearn=no autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: f43e6,350d56069dc98b72 X-Google-Attributes: gidf43e6,public X-Google-Thread: 103376,350d56069dc98b72 X-Google-Attributes: gid103376,public X-Google-ArrivalTime: 1994-10-27 06:29:42 PST Newsgroups: comp.lang.ada,comp.software-eng Path: nntp.gmd.de!xlink.net!fauern!news.th-darmstadt.de!terra.wiwi.uni-frankfurt.de!zeus.rbi.informatik.uni-frankfurt.de!news.dfn.de!swiss.ans.net!howland.reston.ans.net!math.ohio-state.edu!cis.ohio-state.edu!news.sei.cmu.edu!lpb From: lpb@sei.cmu.edu (Loic Briand) Subject: Re: Lines of documentation per LOC Message-ID: <1994Oct26.094543.24213@sei.cmu.edu> Sender: netnews@sei.cmu.edu (Netnews) Organization: The Software Engineering Institute References: <1994Oct25.170005.27711@sei.cmu.edu> Date: Wed, 26 Oct 1994 09:45:43 EDT Xref: nntp.gmd.de comp.lang.ada:16232 comp.software-eng:19258 Date: 1994-10-26T09:45:43-04:00 List-Id: In article , 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 --