Re: Commenting the source code.

From: Eric Sosman (eric.sosman_at_sun.com)
Date: 10/25/04 

Date: Mon, 25 Oct 2004 10:46:33 -0400

Joona I Palaste wrote:
> Malcolm <malcolm@55bank.freeserve.co.uk> scribbled the following:
>
>>"Profetas" <xuxu_18@yahoo.com> wrote
>>
>>>My theory is that commenting whilst you are coding,
>>>will break your concentration on what you were programming.
>>>
>>>If it is something complex.
>>>
>>>Does anybody agree?
>>>
>>
>>Yes. Comments are for people, including you after some time, who need to
>>look at the code after it is finished. If you put in comments during actual
>>writing you may need to take them out, you may find it hard to "comment out"
>>code, and, worst of all, you may invalidate a comment and forget to change
>>it, something no compiler can catch.
>
> One of our source files over at work is rife with comments about some
> obscure kludges that had to be inserted and need to be removed in the
> future. But over the course of the program's development, no one has
> bothered to find out what these kludges exactly are, which part of the
> code they affect, and how (or if) they can be removed. So the file still
> has comments about "This kludge should be removed by version n" when
> we're already in version n+2. Actually the whole file needs complete
> replacing but no one has got around to designing a replacement.

    Having dealt with many such "permanent temporary
fixes," I found myself wishing for a way to make the
compiler complain -- not now, but at some future date,
so the hack would work for the moment but would draw
attention to itself later on. At first, I thought the
compiler ought to have a construct for such things, but
I eventually changed my mind: The compiler, in and of
itself, is not a complete software engineering tool and
should not be (ab)used as such.

    Still, one can often take advantage of assorted
preprocessor symbols that medium-to-large projects often
define. E.g.,

        /* This ugly hack works well enough to let the rest
         * of the system be tested usefully, but should be
         * fixed before we actually release the product.
         */
        #ifdef RELEASE
            #error "Please fix before shipping"
        #else
            /* ugly hack goes here */
        #endif

    Symbols that discriminate "release" from "test" versions
are often useful for this purpose; so, too, are symbols that
specify product versions (you'll ship the hack in version 2.0,
but want to remember to fix it for 2.1). NDEBUG is sometimes
used this way, but "overloading" its meaning is not wonderful.
The main idea is to look for a symbol that will change at some
relevant point in the future, ideally a symbol that is somehow
connected with the need for the hack, and then to plant a time
bomb with a BIG comment explaining what the hack was for and
how to tell whether it can be dispensed with. 

-- 
Eric.Sosman@sun.com

Relevant Pages

  • Re: C# Error CS1034: compiler limit exceeded (2046 characters)
    ... We have always had to hack the wdsl ... I think using client-side XMLHTTP might be easier than what ... Kyril Magnos ... |> manually adding CRLF between each arg but the compiler appears to unfold ...
    (microsoft.public.dotnet.languages.csharp)
  • Re: standard memory allocator alignment issue...
    ... in the struct, minus one for the `char' element, minus the ... of padding bytes *after* the union. ... compiler where that final term would be non-zero, ... I am trying to come up with somewhat "portable" hack that can attempt to ...
    (comp.lang.c)
  • Re: Richard Stallman is responsible for the shrinking economy
    ... Any compiler, open source or not, can have Ken Thompson's ... The point is that besides that particular vulnerability, ... By the way, for a more practical version of a totally invisible hack, I ...
    (comp.arch.embedded)
  • Re: Few doubts (wrong behaviour or correct )
    ... But if a compiler goes to the ... considerable extra effort to implement array bounds checking, ... break code that uses the struct hack. ... In support of the struct hack and similar constructs invoking undefined behaviour... ...
    (comp.lang.c)
  • Re: Remotely controlling a PC - How can one tell this is happening?
    ... > like replacing the DNS-related DLL, ... > In my first posting in this thread, ... > an external sniffer with a completely different control path... ... > bootstrapped the compiler yourself using only source/objects ...
    (comp.security.misc)