Documenting COBOL WAS: Re: Flow chart generators
in [Cobol]
|
From: Pete Dashwood on 28 Oct 2009 19:32 Richard wrote: > 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*. Why? Isn't that what User Manuals are for? > > 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 wrote PLAN and it WASN'T simple enough for an Accountant. Good marketing slogan, though :-) > > >> 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'm not sure I'd want the User Manual included in Source, although I understand that at least then it gets updated when the source does. Extracting to HTML is a very good idea. > > > >> 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. > Yes. I'm not sure what this person was used to, but it wasn't COBOL. > >> 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: Pete Dashwood on 28 Oct 2009 19:52 docdwarf(a)panix.com wrote: > 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 understand your concern, Doc, and I shared it when I first embarked into using third party components. However the keyword here is "application" ["...that would give us deeper knowledge of this part of the _application_ "] You don't have source code for the IO housekeeping routines that transfer data to and from your COBOL program, yet you find this an acceptable risk. By the same token, I don't need source code for a third party Grid component or serial port server, I plug them into my application and they work as documented. If they don't (and, oddly enough, that has NEVER happened in over 10 years now), they would get unplugged pretty quickly and either replaced or referred to the supplier. Only as a last resort whould I st down and write this functionality myself. I only have one lifetime. I cannot and do not want to be an expert on EVERYTHING, and I simply don't have time or inclination to re-invent wheels that someone spent a considerable amount of time inventing already. (Sometimes, components encapsulate specialist knowledge that I would need years to acquire, even if I wanted to.) Sooner or later we have to trust other people to do their job. "Applications" are built by plugging components together. The system architect/designer has complete control of that and can ensure that audit trails for financially sensitive information (for example) are included. You don't have to have a brick factory in order to build a brick house...(But you might want to have a technical standard that the bricks must comply with...) > > (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.) > I have seen component based implementations of two of these (Hospital and Payroll) and they complied with legal requirements just as they would if they weren't component based. Pete. -- "I used to write COBOL...now I can do anything."
From: Anonymous on 29 Oct 2009 11:45 In article <7ks3q3F39lngrU1(a)mid.individual.net>, Pete Dashwood <dashwood(a)removethis.enternet.co.nz> wrote: >docdwarf(a)panix.com wrote: >> 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 understand your concern, Doc, and I shared it when I first embarked into >using third party components. However the keyword here is "application" >["...that would give us deeper knowledge of this part of the _application_ >"] > >You don't have source code for the IO housekeeping routines that transfer >data to and from your COBOL program, yet you find this an acceptable risk. 'You already accept some bit of uncertainty so you can accept more' has not, in my experience, been much of a satisfactory response to an auditor's question of 'How was this number generated?' >By the same token, I don't need source code for a third party Grid component >or serial port server, I plug them into my application and they work as >documented. Are you writing a 'moderately secured system' that gets reviewed by competent auditors? (longtime readers may recall something similar, years ago, when I asked Mr Dashwood about loading tables with 60,000,000 rows) [snip] >> (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.) >> >I have seen component based implementations of two of these (Hospital and >Payroll) and they complied with legal requirements just as they would if >they weren't component based. Are these systems you have written? DD
From: Howard Brazee on 29 Oct 2009 13:50 On Thu, 29 Oct 2009 12:52:34 +1300, "Pete Dashwood" <dashwood(a)removethis.enternet.co.nz> wrote: >I understand your concern, Doc, and I shared it when I first embarked into >using third party components. However the keyword here is "application" >["...that would give us deeper knowledge of this part of the _application_ >"] > >You don't have source code for the IO housekeeping routines that transfer >data to and from your COBOL program, yet you find this an acceptable risk. >By the same token, I don't need source code for a third party Grid component >or serial port server, I plug them into my application and they work as >documented. If they don't (and, oddly enough, that has NEVER happened in >over 10 years now), they would get unplugged pretty quickly and either >replaced or referred to the supplier. Only as a last resort whould I st down >and write this functionality myself. My environment is somewhat different. We have a major application that gets updated periodically along with mods that aren't in the base. So a very large part of programmer's work is in code comparisons and putting the mods back into the changed application. Fewer people and fewer hours are spent in applications development and far more people and hours are spent in what users would consider "black box" work. This is counter to the computer room stereotype that we thought we were moving away from. -- "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: Anonymous on 29 Oct 2009 14:32
In article <d6lje5l92gf4ej8t5m0tqbkendrve8kkkh(a)4ax.com>, Howard Brazee <howard(a)brazee.net> wrote: [snip] >My environment is somewhat different. We have a major application >that gets updated periodically along with mods that aren't in the >base. So a very large part of programmer's work is in code >comparisons and putting the mods back into the changed application. That sounds like 'We received an update and someone needs to change PROGA, PROGB and PROGC again'. Changing the same programs over and over again is, in my experience, almost a sure way to guarantee programmer boredom, stagnation and job-hunting. > >Fewer people and fewer hours are spent in applications development and >far more people and hours are spent in what users would consider >"black box" work. This is counter to the computer room stereotype >that we thought we were moving away from. If a 'black box' is the replacement for a 'glass house' then not much seems to have changed except how readily one can see inside. Corner-Office Idiot: 'How come this costs so much? I thought the New System was supposed to save us money!' Tech Lead: 'The New System saves a lot of money on development. It also requires more money to be spent on maintenance.' Corner-Office Idiot: 'That's just not satisfactory... maybe what we need is Yet Another New System.' Applications Programmer: 'How will any New System take into account satisfying the needs our users have expressed?' (both others, simultaneously): 'That's *your* job.' DD |