Prev: Cyrillic characters
Next: Where to download free Fujitsu COBOL compiler
From: Pete Dashwood on 27 Oct 2009 19:40
Howard Brazee wrote:
> On Mon, 26 Oct 2009 14:45:22 -0500, "HeyBub" <heybub(a)NOSPAMgmail.com>
> wrote:
>
>> Well, admittedly, the Data Division is not self-documenting, but
>> that can be solved by the liberal application of COPY books.
>
> Very good.
>
> I was thinking about CoBOL's self-documenting characteristic.
>
> All code in any? language can be documented. But the best
> documentation is that which is up-to-date and trustworthy. This is
> pretty obvious, but how many shops guarantee that text documentation
> is trustworthy?
>
> If we programmers have to document anyway, it is preferable to have
> documentation tied to the code. Meaningful names doesn't take more
> effort than comments. Designing code to be read isn't that hard.
>
> Of course, if documentation isn't our thing, we can write cryptic,
> disposable code.

I like the fact that some languages have an "auto-document" feature (Java,
C#) but I don't use it. :-) (Sorry, that should be "I haven't used it
YET...I'm planning to have a go at this but it is way down a list of current
priorities...)

If constructs are simple and variables are named in a meaningful way (names
don't have to be long to be meaningful) then any professional programmer
should be able to understand what is going on (This applies to most
languages, including COBOL.)

I think the difference is in emphasis. With COBOL, everything is about
source code, so the source code has to be easily understandable. It simply
costs more if it isn't. With OO languages you may be using objects and
components from third parties that you don't even HAVE the source code for,
so the emphasis is on the functionality working as documented, rather than
the source being well documented. I learned a long time ago to provide help
files with components, not just for people I was passing components to, but
for myself as well. Yes, you CAN use an Object Browser to reveal the secrets
of an object component but this gets pretty tedious and these days I only do
that as a last resort when I have an undocumented component. (It is
increasingly common practice for components to document themselves and you
can specifically ask them to show you this documentation...)

I had occasion to discuss this with a Client a few days ago. He is not from
a COBOL background and he felt that the use of an asterisk in column 7 and
comments then inserted as lines made the source LESS readable. He was
talking about some COBOL source that is part of a system he is migrating for
someone else.

I asked him if he had a problem with the extensive comments that the Toolset
adds to transformed source (I deliberately made it generate comments so that
programmers coming to do maintenance on Legacy COBOL AFTER migration, and
not having been privy to the process, could understand what was happening.)

One of the options in Transformation allows you keep the original code in
the program and the tool comments it out, or, you can simply have it removed
and be left with the transformed code. (Most people opt for retaining it, at
least until they come to "trust" the transformation tool...)

Surprisingly, he said he had no problem with comments generated by the
Toolset. Further discussion revealed that he didn't mind the use of "*>" as
this usually indents the comment to where it is needed or can appear on the
same line as the construct it is commenting on. (The toolset uses "*>" for
comments.)

So * in column 7 is not as useful as *>, at least to a non-COBOL eye. (I
concede it is a sample of one, but it was interesting to me.)

It would seem that the LOOK of the comments has an effect on their
usefulness.

When I first started writing COBOL there was a local standard that required
a paragraph starting with "NOTE" at the beginning of each section.

The trouble is that many programmers are not wizards of English and don't
like writing anything other than code... :-)

So you end up with : "This code accesses the Master file. Then it processes
it. Then it closes it."

All of which is pretty easily gleaned from the procedure names and verbs
used...

For myself, when writing COBOL I add comments to explain the concept of what
is going on or why a particular approach was chosen, or pitfalls to be aware
of when maintaining the code. The mechanics are (or should be...) clear from
the code itself.

But overall, I much prefer the object approach where Overview/concepts,
Methods, Properties, and Events are all documented but you don't need to
read it unless you want to.

Pete.
--
"I used to write COBOL...now I can do anything."


From: Richard on 27 Oct 2009 20:53
On Oct 28, 12:40 pm, "Pete Dashwood"
<dashw...(a)removethis.enternet.co.nz> wrote:
> Howard Brazee wrote:
> > On Mon, 26 Oct 2009 14:45:22 -0500, "HeyBub" <hey...(a)NOSPAMgmail.com>
> > wrote:
>
> >> Well, admittedly, the Data Division is not self-documenting, but
> >> that can be solved by the liberal application of COPY books.
>
> > Very good.
>
> > I was thinking about CoBOL's self-documenting characteristic.
>
> > All code in any? language can be documented.    But the best
> > documentation is that which is up-to-date and trustworthy.    This is
> > pretty obvious, but how many shops guarantee that text documentation
> > is trustworthy?
>
> > If we programmers have to document anyway, it is preferable to have
> > documentation tied to the code.    Meaningful names doesn't take more
> > effort than comments.     Designing code to be read isn't that hard..
>
> > Of course, if documentation isn't our thing, we can write cryptic,
> > disposable code.
>
> I like the fact that some languages have an "auto-document" feature (Java,
> C#) but I don't use it. :-) (Sorry, that should be "I haven't used it
> YET...I'm planning to have a go at this but it is way down a list of current
> priorities...)
>
> If constructs are simple and variables are named in a meaningful way (names
> don't have to be long to be meaningful) then any professional programmer
> should be able to understand what is going on (This applies to most
> languages, including COBOL.)

"any professional programmer" should not be the target, it should be
understood by managers and accountants*.

Actually there are hundreds of languages which I have seen and haven't
a clue about what is _really_ going on. Though superficially I may
think that I do, one can't know

* I recall when the ICL 2903 was announced in 1973 there was a
marketing phrase: "So simple that even an accountant can understand
it".


> I think the difference is in emphasis. With COBOL, everything is about
> source code, so the source code has to be easily understandable. It simply
> costs more if it isn't. With OO languages you may be using objects and
> components from third parties that you don't even HAVE the source code for,
> so the emphasis is on the functionality working as documented, rather than
> the source being well documented. I learned a long time ago to provide help
> files with components, not just for people I was passing components to, but
> for myself as well. Yes, you CAN use an Object Browser to reveal the secrets
> of an object component but this gets pretty tedious and these days I only do
> that as a last resort when I have an undocumented component. (It is
> increasingly common practice for components to document themselves and you
> can specifically ask them to show you this documentation...)

I find that I don't need to document for other programmers but I do
need to documents for the program's users. So I incorporate the user
document into the source code at the appropriate points and then
extract this, usually to HTML.



> I had occasion to discuss this with a Client a few days ago. He is not from
> a COBOL background and he felt that the use of an asterisk in column 7 and
> comments then inserted as lines made the source LESS readable. He was
> talking about some COBOL source that is part of a system he is migrating for
> someone else.
>
> I asked him if he had a problem with the extensive comments that the Toolset
> adds to transformed source (I deliberately made it generate comments so that
> programmers coming to do maintenance on Legacy COBOL AFTER migration, and
> not having been privy to the process, could understand what was happening..)
>
> One of the options in Transformation allows you keep the original code in
> the program and the tool comments it out, or, you can simply have it removed
> and be left with the transformed code. (Most people opt for retaining it, at
> least until they come to "trust" the transformation tool...)
>
> Surprisingly, he said he had no problem with comments generated by the
> Toolset. Further discussion revealed that he didn't mind the use of "*>" as
> this usually indents the comment to where it is needed or can appear on the
> same line as the construct it is commenting on. (The toolset uses "*>" for
> comments.)
>
> So * in column 7 is not as useful as *>, at least to a non-COBOL eye. (I
> concede it is a sample of one, but it was interesting to me.)
>
> It would seem that the LOOK of the comments has an effect on their
> usefulness.

What is easy to understand is entirely what one is used to.


> When I first started writing COBOL there was a local standard that required
> a paragraph starting with "NOTE" at the beginning of each section.
>
> The trouble is that many programmers are not wizards of English and don't
> like writing anything other than code... :-)
>
> So you end up with : "This code accesses the Master file. Then it processes
> it. Then it closes it."
>
> All of which is pretty easily gleaned from the procedure names and verbs
> used...
>
> For myself, when writing COBOL I add comments to explain the concept of what
> is going on or why a particular approach was chosen, or pitfalls to be aware
> of when maintaining the code. The mechanics are (or should be...) clear from
> the code itself.
>
> But overall, I much prefer the object approach where Overview/concepts,
> Methods, Properties, and Events are all documented but you don't need to
> read it unless you want to.
>
> Pete.
> --
> "I used to write COBOL...now I can do anything."

From: Anonymous on 28 Oct 2009 08:46
In article <7kpen1F3bc69qU1(a)mid.individual.net>,
Pete Dashwood <dashwood(a)removethis.enternet.co.nz> wrote:

[snip]

>I think the difference is in emphasis. With COBOL, everything is about
>source code, so the source code has to be easily understandable. It simply
>costs more if it isn't. With OO languages you may be using objects and
>components from third parties that you don't even HAVE the source code for,
>so the emphasis is on the functionality working as documented, rather than
>the source being well documented.

With all due respect to those who write and use such systems, Mr Dashwood,
my first response to the above was 'Holy Ned... what set of competent
auditors of an even moderately secured system would be satisfied by
hearing 'We don't have the source code or anything else that would give us
deeper knowledge of this part of the application; all we gotta do is plug
in a value here and Something Else comes out there and we run with that'?'

(I use 'moderately secured' to refer to things like Stock-trading or
Hospital-Admission/Treatment or Payroll systems, things which have aspects
covered by Federal Law (eg the Health Insurance Portability and
Accountability Act, or HIPAA) in the United States of America.)

DD

From: Howard Brazee on 28 Oct 2009 11:30
On Wed, 28 Oct 2009 12:40:15 +1300, "Pete Dashwood"
<dashwood(a)removethis.enternet.co.nz> wrote:

>So you end up with : "This code accesses the Master file. Then it processes
>it. Then it closes it."
>
>All of which is pretty easily gleaned from the procedure names and verbs
>used...

Way, way too common, in my experience.

>For myself, when writing COBOL I add comments to explain the concept of what
>is going on or why a particular approach was chosen, or pitfalls to be aware
>of when maintaining the code. The mechanics are (or should be...) clear from
>the code itself.

The most useful comments I have seen are the comments that tell us why
a particular approach was taken and which user put that requirement
in. Stuff that would be in the requirements, if we could find them
(and if they were updated when the writer actually got the details
about what was wanted).

--
"In no part of the constitution is more wisdom to be found,
than in the clause which confides the question of war or peace
to the legislature, and not to the executive department."

- James Madison
From: tlmfru on 28 Oct 2009 18:16

Howard Brazee <howard(a)brazee.net> wrote in message
news:eloge598qut3oaven42ttiimbqhfmqk2nu(a)4ax.com...
> The most useful comments I have seen are the comments that tell us why
> a particular approach was taken and which user put that requirement
> in. Stuff that would be in the requirements, if we could find them
> (and if they were updated when the writer actually got the details
> about what was wanted).
>

Hear, hear. Keeping program specs (if indeed they get written in the first
place) up to date is an opium dream. So including the why and who with the
source code (or, begging PD's pardon, help files with components) along with
a reference to any other source document needed to understand it is the most
sensible thing to do. Although I HAVE heard of installations with programs
in production for which the source has been lost.

PL


 |  Next  |  Last
Pages: 1 2 3 4 5 6
Prev: Cyrillic characters
Next: Where to download free Fujitsu COBOL compiler