From: Niklas Holsti <nobody@nowhere.fi>
Subject: Re: Request for comments on simple Ada program
Date: Wed, 16 Nov 2005 11:03:12 +0200
Date: 2005-11-16T11:03:12+02:00 [thread overview]
Message-ID: <NyDef.9004$4x2.2000@reader1.news.jippii.net> (raw)
In-Reply-To: <m2mzk5r47u.fsf@hugin.crs4.it>
Jacob Sparre Andersen wrote:
> Writing the function of the procedure in a comment is OK, although I
> would like to keep all the non-checkable stuff outside the source
> file.
>
> Jacob (who believes that the optimal comment/code ratio is zero)
People differ. In my Ada code, the "comments" average 33% of
non-blank lines (59% for package specs, 23% for package bodies,
and note that I never repeat comments from specs in bodies). I
still occasionally find it hard to *fully* understand code from a
couple of years back. It's not the details -- I know what
N := N + 1 means by itself -- but the background assumptions,
intentions, limitations, usage rules, interactions.
I put "comments" in quotes above, because I think that this is a
bad case of mis-naming in programming language terminology. The
word "comment" implies something skimpy, an addition, a note; in
my view, what is needed is a rationale, description or motivation
that is mainly written *before* the code itself.
As for keeping such text in separate design documents, I would do
it if a customer demanded it, but I think it would be much harder
to manage changes, versions and configurations accurately. Still,
some very high-level descriptions are nice to keep apart from the
source-code, if they are not outdated by day-to-day code changes.
--
Niklas Holsti
Tidorum Ltd
niklas holsti tidorum fi
. @ .
next prev parent reply other threads:[~2005-11-16 9:03 UTC|newest]
Thread overview: 112+ messages / expand[flat|nested] mbox.gz Atom feed top
2005-11-15 16:03 Request for comments on simple Ada program Maciej Sobczak
2005-11-15 17:43 ` Samuel Tardieu
2005-11-15 17:47 ` Samuel Tardieu
2005-11-15 21:28 ` Jacob Sparre Andersen
2005-11-15 21:53 ` Samuel Tardieu
2005-11-16 9:10 ` Anders Wirzenius
2005-11-15 21:55 ` Samuel Tardieu
2005-11-16 9:03 ` Niklas Holsti [this message]
2005-11-16 14:21 ` Jacob Sparre Andersen
2005-11-16 17:08 ` Niklas Holsti
2005-11-16 7:11 ` Brian May
2005-11-15 18:29 ` jimmaureenrogers
2005-11-15 19:33 ` tmoran
2005-11-16 14:46 ` jimmaureenrogers
2005-11-16 18:05 ` Martin Dowie
2005-11-16 19:54 ` tmoran
2005-11-15 18:52 ` Martin Krischik
2005-11-15 19:33 ` tmoran
2005-11-16 3:10 ` Ada Quality and Style book discussion Anonymous Coward
2005-11-16 4:09 ` tmoran
2005-11-16 5:49 ` Simon Wright
2005-11-16 7:03 ` Martin Dowie
2005-11-17 4:49 ` Anonymous Coward
2005-11-17 6:48 ` Martin Dowie
2005-11-17 11:45 ` Georg Bauhaus
2005-11-17 12:37 ` Stephen Leake
2005-11-17 13:24 ` Georg Bauhaus
2005-11-17 23:15 ` Stephen Leake
2005-11-19 20:28 ` Don't use the "use" clause Anonymous Coward
2005-11-19 20:35 ` Ed Falis
2005-11-21 17:36 ` David Emery
2005-11-21 19:20 ` Ed Falis
2005-11-21 22:21 ` David Trudgett
2005-11-21 22:51 ` Ed Falis
2005-11-22 0:15 ` Anonymous Coward
2005-11-23 4:09 ` Ed Falis
2005-11-23 19:26 ` tmoran
2005-11-19 21:48 ` Dmitry A. Kazakov
2005-11-19 22:33 ` Simon Wright
2005-11-19 23:40 ` Anonymous Coward
2005-11-20 11:07 ` Dmitry A. Kazakov
2005-11-20 19:50 ` Jeffrey R. Carter
2005-11-20 2:53 ` Stephen Leake
2005-11-20 3:57 ` Anonymous Coward
2005-11-20 10:44 ` Pascal Obry
2005-11-20 19:48 ` Jeffrey R. Carter
2005-11-22 5:11 ` greptree lou
2005-11-22 6:08 ` greptree Simon Wright
2005-11-25 1:00 ` greptree Björn Persson
2006-01-23 12:51 ` Don't use the "use" clause adaworks
2006-01-23 20:21 ` Jeffrey R. Carter
2006-01-24 2:27 ` Stephen Leake
2006-01-24 3:32 ` Ed Falis
2006-01-24 4:44 ` Jeffrey R. Carter
2006-01-24 22:53 ` Stephen Leake
2006-01-24 8:54 ` Dmitry A. Kazakov
2006-01-24 9:48 ` Martin Dowie
2006-01-24 10:28 ` Dmitry A. Kazakov
2006-01-24 13:30 ` brian.b.mcguinness
2006-01-24 20:03 ` Simon Wright
2006-01-24 23:00 ` Stephen Leake
2006-01-25 4:58 ` Jeffrey R. Carter
2006-01-24 23:38 ` Randy Brukardt
2006-01-25 14:49 ` Dmitry A. Kazakov
2006-01-25 21:46 ` Randy Brukardt
2006-01-26 9:14 ` Dmitry A. Kazakov
2006-01-27 1:04 ` Randy Brukardt
2006-01-27 15:23 ` Dmitry A. Kazakov
2006-01-27 16:35 ` Georg Bauhaus
2006-01-27 23:09 ` Randy Brukardt
2006-01-27 23:18 ` Randy Brukardt
2006-01-28 10:41 ` Dmitry A. Kazakov
2006-01-24 22:55 ` Stephen Leake
2006-01-24 9:42 ` Martin Dowie
2006-01-24 23:02 ` Stephen Leake
2006-01-25 9:14 ` Martin Dowie
2006-01-25 11:01 ` Peter Amey
2006-01-25 11:06 ` Martin Dowie
2006-01-25 20:07 ` Jeffrey R. Carter
2006-01-31 2:24 ` Stephen Leake
2006-02-09 5:13 ` Anonymous Coward
2005-11-17 20:55 ` Ada Quality and Style book discussion Simon Wright
2005-11-18 0:44 ` Larry Kilgallen
2005-11-19 20:56 ` Anonymous Coward
2005-11-19 22:41 ` Simon Wright
2005-11-20 0:03 ` Anonymous Coward
2005-11-17 4:23 ` Ada Quality and Style book discussion ("_Type" suffix) Anonymous Coward
2005-11-17 10:51 ` Martin Dowie
2005-11-19 21:52 ` Anonymous Coward
2005-11-20 15:50 ` Martin Dowie
2005-11-17 11:34 ` Georg Bauhaus
2005-11-17 11:53 ` Martin Dowie
2005-11-17 13:26 ` Georg Bauhaus
2005-11-17 12:26 ` Brian May
2005-11-17 13:45 ` Martin Dowie
2005-11-17 14:22 ` Marc A. Criley
2005-11-17 14:50 ` Martin Dowie
2005-11-18 3:04 ` Brian May
2005-11-18 9:23 ` Maciej Sobczak
2005-11-18 14:00 ` Marc A. Criley
2005-11-18 11:48 ` Java exception model. Was: " Peter C. Chapin
2005-11-18 13:18 ` Dmitry A. Kazakov
2005-11-19 18:06 ` Peter C. Chapin
2005-11-19 18:58 ` Dmitry A. Kazakov
2005-11-21 22:38 ` Brian May
2005-11-21 23:27 ` Brian May
2005-11-18 22:33 ` Simon Wright
2005-11-17 14:03 ` Hyman Rosen
2005-11-20 19:41 ` Jeffrey R. Carter
2005-11-20 20:43 ` Dmitry A. Kazakov
2005-11-21 0:00 ` Simon Wright
2005-11-16 13:51 ` Ada Quality and Style book discussion Marc A. Criley
replies disabled
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox