Xref: utzoo comp.misc:5401 comp.lang.misc:2714
Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!uflorida!novavax!twwells!bill
From: bill@twwells.uucp (T. William Wells)
Newsgroups: comp.misc,comp.lang.misc
Subject: Re: Program Errors and developement environment
Message-ID: <756@twwells.uucp>
Date: 8 Mar 89 23:11:55 GMT
References: <4352@enea.se> <2950@hound.UUCP> <3998@ttidca.TTI.COM>
Reply-To: bill@twwells.UUCP (T. William Wells)
Followup-To: /dev/null
Organization: None, Ft. Lauderdale
Lines: 53
Summary:
Expires:
Sender:
Distribution:
Keywords:

In article <3998@ttidca.TTI.COM> hollombe@ttidcb.tti.com (The Polymath) writes:
: This is the reason I delimit all comments line by line and have fought
: to get that practice included in several coding standards.
:
: C example:
:
:      /* This comment is */
:      /* delimited line  */
:      /* by line.        */
:
:      /*
:         This is the way
:         too many other
:         people do it.
:      */
:
: The above example is a trivial oversimplification that doesn't show how
: the second form can cause problems.  I've seen several pages of comments,
: including some that looked remarkably like source code, delimited with a
: single set of /* */.

There's a much better way of dealing with this: have a lint complain
when a /* occurs in a comment or a /* is not terminated.  Such a
program is very short, less than a hundred lines (write it as a FSM),
and will catch all errors of this type.  Add it to your toolkit and
stop worrying about this problem. No, I don't have such a program
handy; I typically don't make this particular mistake and so I have no
need for one. (I have my own favorite mistakes. :-)

(I know of two compilers that actually do this check and deliver a
warning when a comment is found within a comment.)

The line-by-line style is more difficult to read (one must mentally
subtract the /* */ on each line), more difficult to maintain (one
must remove the /* */ before reformatting text [don't say anything
about emacs, please; all the world's not emacs]), and more difficult
to write (one has to put the pesky things in, often after one has
finished writing the comment).  Not only that, it doesn't really
solve the problem; only discipline will solve that problem, absent an
appopriate tool.  Why use this comment style when there is a simple
tool that eliminates the problem in better ones?

One final note: this is my opinion, I offer my solution to the
problem solely as information with which to aid in choosing a comment
style. I *will not* debate this. I suggest that you don't debate it
either; such debates are rarely fruitful. Just make up your own mind,
pick a consistent style, and adhere to it.

---
Bill
{ uunet | novavax } !twwells!bill
(BTW, I'm going to be looking for a new job sometime in the next
few months.  If you know of a good one, do send me e-mail.)