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=-1.9 required=5.0 tests=BAYES_00 autolearn=ham autolearn_force=no version=3.4.4 X-Google-Language: ENGLISH,ASCII-7-bit X-Google-Thread: 103376,e61c8636ef35379d X-Google-Attributes: gid103376,public X-Google-ArrivalTime: 2001-01-22 16:15:35 PST Path: supernews.google.com!sn-xit-02!sn-xit-04!supernews.com!xfer13.netnews.com!netnews.com!newsfeed.skycache.com!Cidera!typhoon.sonic.net!uunet!sac.uu.net!usenet.rational.com!not-for-mail From: "Mark Lundquist" Newsgroups: comp.lang.ada Subject: Re: Examples in Docs, was Re: Escape Sequences in Strings Date: Mon, 22 Jan 2001 15:58:57 -0800 Organization: Rational Software Message-ID: <94ii8d$1iv$1@usenet.rational.com> References: <93objj$guk$1@nnrp1.deja.com> <93q77h$rr6$1@nnrp1.deja.com> <940f9j$nj2$1@nnrp1.deja.com> <94299p$8dd$1@nnrp1.deja.com> <94a2jj$tc2$1@nnrp1.deja.com> <94c73f$hs9$1@nnrp1.deja.com> NNTP-Posting-Host: ext-3038.rational.com X-Priority: 3 X-MSMail-Priority: Normal X-Newsreader: Microsoft Outlook Express 5.00.2314.1300 X-MimeOLE: Produced By Microsoft MimeOLE V5.00.2314.1300 Xref: supernews.google.com comp.lang.ada:4345 Date: 2001-01-22T15:58:57-08:00 List-Id: Robert Dewar wrote in message news:94c73f$hs9$1@nnrp1.deja.com... > In article <94a2jj$tc2$1@nnrp1.deja.com>, > mark_lundquist@my-deja.com wrote: > > I think the idea of embedded hyperlinks in comments to > > navigate out to supporting documentation of the kind you > > mention could really be > > worthwhile (DING! Cue for Bob-Leif-XML-followup :-) :-) :-) > > Generally I much prefer ALL technical documentation (as opposed > to user documentation) of the code to be in the code. I was involved with the IEEE POSIX P1003.5c standardization-- the Ada binding to network services. That's a pretty reasonably big-sized document :-) I'd hate for that to have to go into the source code as comments... > Why? > Simple, in my experience VERY few programmers have the > discipline to maintain external documents, so they quickly get > out of sync and become completely useless. > > It is hard enough for most people to be diligent about > maintaining comments and documentation that *are* part of > the source code. True enough... I think embedded HLs in comments would help. They effectively increase the "proximity" of the document to the code (just a click away) so people hopefully care a little more that the documentation be right. I find super comment-heavy code cumbersome to work with. > You really have to develop the exact opposite opinion from > "comments don't really matter and have no effect", and consider > that a bad spelling in a comment is a real bug :-) Sure a bad > spelling is not serious, but the attitude that will not > tolerate bad spelling in program comments is one that goes > along with a commitment to maintaining good internal > documentation. Yes, that's the attitude one has to develop. At least we agree that documentation is important, wherever it goes :-) and that the "all that matters is the code" mindset is one that has to be eliminated. --- Just to be irrelevant... It's [flame-bait :] analogous :-) to attitudes about style and design principles. Some people think that the most important thing about a program is that it be correct (which is only true for the version of a program that is deployed). Under that view, a kludgy, brittle, crappy program that has been debugged into existence and finally gives the right answer is infinitely preferable to a well-designed, elegant program that has a minor bug (let's say, a one-line bug) so that it gives a wrong answer. In fact, I once worked with a manager that held this opinion. But, I want software that both is well-written and gives the right answer, because that software by definition is easy to understand and easy to change in the future, so it will be fun to work on and not such a pain to change that years go by with nobody being able to find the time or work up the nerve to overhaul it. Given that, I'll take Program Number Two any day, because it is *much* closer (just a minor bug away) from the ideal of correctness and elegance, whereas the "correct" program will never, ever get there.