Path: utzoo!utgpu!news-server.csri.toronto.edu!rpi!zaphod.mps.ohio-state.edu!uwm.edu!linac!att!ucbvax!lynx.northeastern.edu!cschmidt
From: cschmidt@lynx.northeastern.edu
Newsgroups: comp.lang.pascal
Subject: Re: Borland flaming
Message-ID: <memo.898989@lynx.northeastern.edu>
Date: 7 Apr 91 16:11:33 GMT
Sender: daemon@ucbvax.BERKELEY.EDU
Lines: 79

> Let's face it, Borland has a good track record in their C++
> development, and I have no reason to flame them for anything.

I will give you a reason for free: Borland documentation is awful.

To prove this assertion would require a much longer critique than you
would care to read.  However, I can illustrate my assertion with a few
examples.  I hope you will agree that, just as these few examples do
not prove the assertion, so too the assertion would not be disproved
should you disqualify an example on the basis of currency or overall
importance.

o   The Turbo C++ manuals describe several methods to tell the
    compiler whether to regard the input program as "C++ code" or as
    "C code", but I have not found an explanation in any of the four
    Turbo C++ manuals of how the results might differ.  How is it
    possible that Borland could describe a compiler switch without
    explaining its effect?

    I could speculate that the difference might have something to do
    with "type-safe linkage", but that term is not mentioned in any of
    the Turbo C++ manuals, as far as I have determined.  (However,
    Borland manuals are poorly organized, so it is hard to find
    things.  I am certain that "type-safe linkage" does not appear in
    any form in any of the indexes.)

o   The following excerpt from the Turbo Assembler User's Guide (page
    529 in my edition) is Borland's explanation of what is commonly
    known as "scope", in regard to field names within structure
    defintions:

    > They say you can't take it with you but, just in case they're
    > wrong, this example shows how to create a variable with three
    > fields, storing your net worth in dimes, nickels, and pennies in a
    > structure named Heaven.  The fields Dimes and Nickels are unique
    > to the structure.  Pennies, though, occurs twice.  First, there's
    > Pennies outside the structure's pearly gates, and then there's
    > Pennies from Heaven.

    The reader's task is more difficult when useful information is
    hidden within nonsense like this, and there's lots of nonsense
    like this in Borland manuals.  I don't go to technical manuals to
    find amusement or entertainment.  It is tedious to wade through
    nonsense like this to find the information I need.

    Perhaps if the Borland documentation people spent less time
    writing long tutorials and weaving nonsense into their prose, they
    could devote more time to their primary mission, which is to
    produce accurate, concise, and complete technical documentation.

o   In Turbo Pascal 5.0, unsigned integers are not allowed as labels
    in case statements, even when the case statement selector
    expression is an unsigned integer.  The workaround I employed was
    to use equivalent negative values as case statement labels for
    values greater than 32767.

    In Turbo Pascal 5.5, unsigned integers ARE allowed in case
    statement labels, and negative integers are NOT allowed when the
    case statement selector expression is unsigned.  This means the
    workaround I employed was no longer valid.  My old code would not
    even compile.

    There was no mention of any of this in the Borland documentation.
    Borland must document these things if they expect to be taken
    seriously by professional programmers.  One programmer I know said
    that "Turbo Pascal is a joke".  He does not appreciate Turbo
    Pascal's many strengths, and he probably never will unless the
    Borland manuals develop a more serious style.

The most effective thing Borland could do to improve their image among
professional programmers would be to improve their documentation,
since their compilers are already pretty good.  At the very least,
Borland should provide complete revision details with product
upgrades.  If they want respect from professional programmers, they
should show respect for us by providing smart documentation written
for grownups.

Christopher Schmidt
cschmidt@lynx.northeastern.edu