Re: Reviving REMARKS

<john@xxxxxxxxxxxxxxxx> wrote in message
news:1123037908.989224.99930@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
> In fact the structured layout of the IDENTIFICATION DIVISION with its
> fixed paragraph names encouraged the inclusion of significant
> documentation in a standardized way. Every language has a commenting
> facility. What was unique about the ID DIV was that it had a standard
> format. The standard mavens, in their eternal and rather foolish quest
> to make COBOL "just like" every other language gave up some of its
> unique virtues.
I think they failed if that was their goal. COBOL is awfully quirky, always
will be, though I don't expect huge changes to the COBOL 2015 Standards.

> BTW the "self documenting" nature of the language does not tell the
> person reading a program years later the who what when why of the
> creation of the program.
Self documenting means that you don't need comments - the code is "self
documenting".
But anyhooo..

Who - Some contractor who left 5 years ago
When - 5 years ago
Why - A 5 year old requirement for something

One of the things I do when getting into code is to take the god awful
"documentation prologs" out of programs (if allowed) and if not move them to
the end. Who made a change is irrelevant for the most part (code ownership
is an outdated paradigm), when they made it _might_ be useful, but not if
it's more than a few months ago at which point it's rarely useful to know,
and more often the comments are "undone" later on. It's kind of like
prohibition - if you stop reading history at a certain point all of america
is tea total. The issue with comments is that they require maintenance
JUST like source code.

Far more useful is a good source code management tool. It records that junk
(who what) for you.

Far more useful is someone or some group being responsible for maintaining a
list of the actual requirements requested, approved, executed. That's what
QA uses...and that philosophy exists from mainframe accounting apps to
console games.

As someone once said, "Function is King" and the source code is NOT the
place to document function as function is nearly ALWAYS >>>>> a program.

> And without someencouragement programmers
> will take the easy way out.
Which is why shops have "standards".
My standard is to start each paragraph with
*----------------------------------------------------------------------*
*
*
*----------------------------------------------------------------------*
LOOKUP-CUSTOMER-PHONE-NUMBER.

Why? Because I like the spacing. Why don't I comment ? Because I figure
that the paragraph makes it clear.
I don't need to write "Look up the customer phone number because this is the
part of the program where we get the phone number to attach it to his call
history report and key into our other data".
If there was something unusual (then I may add something). I've NEVER had
anyone tell me that they didn't understand the code I had written. I follow
basic rules - name things in a simple manner, and don't do things that you
don't imply.


> How many internally documented program
> written in Java or Perl have you seen lately?

All of them. Find me any usable product/API/Freeware that doesn't have them?
Someone close to me has asked me for help with some undocumented Java...but
it was clearly written by a PL/I programmer (it was _that_ obvious). That's
my exception. People that I work with - everything has been commented and
nauseatingly so - it's kind of mandated.

Most documentation for Java APIs are generated from Java comments.
Reusable objects are worthless without the APIs.
I find that more often that NO comments I see POOR comments. The worst
comments I've ever seen are PL/I and then COBOL comments ...I've seen things
like:

* DO NOT update customer if it is Jamie
IF Rajinder THEN
continue
ELSE
update
END-IF

One assumes that Jamie in A/R was sacked and Rajinder took over.

Or even.
* Use the values (B)lue, (R)ed from the Table for available Colors.

Before the DBA decides to make (Y)ellow a valid value too...

> In a text book, maybe.
> A "generalized commenting facility" may as well be no facility at all.
> Programmers are busy and will skip over it.
It's very simple. If there needs to be comments in the code, then
management mandates comments. If comments are not added then you started
giving low ratings and firing people. Of course, one then would ask for
"quality comments" etc etc This is why you have different people in teams -
the "LEADS" and the "DUMBASSES" :-) One makes sure the other is doing
well...no?

Basic rule of thumb - don't let ANYTHING install without a review. In
public companies not doing this would in most cases violate Sarbanes Oxley
if there is anything that will affect any financials - which is just about
anything these days. It should be done to protect customers, clients,
networks, systems, managers, personal pride or whatever...If what you're
doing is for personal use then one assumes that you don't have short term
memory issues combined with disorganized code.

If the review indicates that the code is unclear then it should be
rewritten, or clarified. Often refactoring clarifies more than commenting.

<DISCLAIMER>
That is of course for those of us who still believe that maintenance of
source code is an issue

> (end grump)
>
> John Culleton
Kind of a small grump I hope. Seems to me that comments and their location
is somewhat of a trivial issue. :-)

JCE


.

Relevant Pages

  • Re: Pascal - C (2)
    ... and strlcat. ... Source code in standard C, and full documentation, are all ...
    (comp.lang.c)
  • Re: The Problems of TeX
    ... many TeX distributions did not come with it - OzTeX is one (in ... If your definition of "not exotic" is "everything that was standard x ... The MacTeX distribution is flawed in that it fails to provide the simple ... silly because it's purely down to a lack of decent documentation. ...
    (comp.text.tex)
  • Re: kernel man pages
    ... > Non standard. ... Unless you write device drivers that depend on some of these. ... > kernel always changes - the SOURCE is the documentation. ... TeX) and the source code to be compiled. ...
    (comp.os.linux.development.system)
  • VHDL Library Madness
    ... the documentation, but it's a tough thing to get changed. ... Appnote code is the hardest to fix. ... some coding standard. ... , go through all the example code which has "bad" libraries, ...
    (comp.lang.vhdl)
  • Re: CRT and Win32 SDK
    ... However, it might give a reader an impression that when doing embedded programming one typically has a full-fledged language at hand, where in effect the runtime library implements what the OS would provide on e.g. a PC. ... The C and C++ standards differentiate between hosted and free-standing implementation to deal with the special constraints of embedded programming, where free-standing doesn't need to provide all of the language's standard library, but even that distinction does in practice not go far enough: it might be that fundamental language features such as static variables and exceptions are not available on the embedded platform's language implementation. ... Both the user-mode Win32 API and the kernel ... The documentation remarks are very important parts of that documentation and form the main part of it. ...
    (microsoft.public.vc.language)