I am a great believer in having my source code liberally sprinkled with documentation in the form of comment lines those with an asterisk in column seven.
Any program which does not contain comments is immediately suspect - it may actually work, but how easy is it to maintain or modify? There may be separate written documentation, but there re distinct advantages in producing self- documenting code:.
It helps if all comments are in lower-case, to differentiate from actual commands which should always be in upper-case. Leave only one space between the asterisk in column seven and the start of the comment - more spaces are laborious to enter in the first place, and certainly don't make the comments easier to read. There is one acid test to prove that your program is adequately documented - can you reconstruct all the written documentation from your source code?
If the answer is NO, then you have failed. There are some products available nowadays which will do the job for you - they read your source code and produce all the separate documentation that you require.
It should be obvious, therefore, that products such as these cannot extract information which is not there to begin with. This is also the best place in which to record other useful information which will serve as an introduction to the program as a whole. The remainder should be included as comment lines. Even though all of the above information can be obtained by close examination of the code, it saves a lot of time and time is money!
Items which are not subdivided are known as elementary items. Items which are subdivided are known as group items, with the record name being equivalent to the highest level of group item. This layout, however, is totally unacceptable in a structured program because it is not easy to determine which elementary items go with which group items.
It would be easier to read if some sort of indentation was used to differentiate between the various level numbers, and if there was some space between the data name and the picture clause. The following example is the best because it indents both the level number and its associated dataname. Note that each different level number is aligned in a separate column, making it easier to spot any mistakes.
Note that all the picture clauses are aligned in the same place, usually at column Where a data name flows into this column the most common practice is to put the picture clause on the following line, thus keeping the alignment consistent, eg:. The effect of items c and d is that the data names for one level are aligned in the same column as the level numbers for the next level. This may seem irrelevant, but I think that it looks better.
When using the QEDIT text editor in full-screen mode it is possible to define the tab stops at columns 8,12,16,20,24,28 etc, therefore the same tab settings can be used for both level numbers and data names. Now for some advice on how to describe headings for batch reports. Here are three ways of describing the same print line:.
Each record definition should be allocated its own mnemonic which should then be attached to all data items within that record. The use of a prefix also makes it easier to search through your source code with your particular text editor to list all those places in a program where a record is referenced:. COBOL allows data names to be up to 30 characters in length. Item names should convey some sort of description as to their content, and in order not to exceed this character limit it is sometimes necessary to use abbreviated terms.
Whatever abbreviation is chosen it is important that the same one is used throughout the system. For example, the following combination of item names within the same system is very sloppy Where the item is subsequently defined within a program's data division eg: in the dataset buffer, the screen buffer, or a print buffer it is also a very good idea to keep to the same spelling. The only difference should be in the prefix, which acts as an identifier for the particular buffer.
This is done by appending a 2 digit sequence number starting at "01" to each occurrence of that item name. There should then be a direct relationship between the hard-coded number in the forms file and the occurrence number within the COBOL array, as demonstrated in the following example:. Each item name should be prefixed by a different mnemonic depending on the record definition in which it appears.
Other standards say that the prefix should be two characters in order to denote the general usage, as in the following:. However, I much prefer to see groupings of items which are related logically, rather than functionally, as in the following:.
Even though each item has a different function, they are all logically related, as they are concerned with that particular table and no other. It also makes it easier to search through the source code to find any reference to this data area simply by specifying a search string of "T01".
The following definition is also acceptable, but it has a distinct advantage when using the COBOL'85 compiler, which allows a group of data items to be reset to blanks or spaces with a single statement. Although the item TMAX has been taken out of the original layout and changed from an 05 level to an 01 level it has still retained the T prefix to show that it is still related logically.
These should be defined in their proper sequence so that it is easy to locate any individual data item when searching through a program listing.
This avoids the need to produce a cross-reference listing which incurs a considerable overhead, both in compilation time and printing time. It can take a long time to debug a program if the same subscript is accidentally used to reference two different tables at the same time, or two different subscripts are accidentally used to reference the same table at the same time.
This cannot easily be confused with TMAX , which is used to indicate the maximum number of entries the table may contain, and TLAST which indicates the actual number of entries in the table at present. Condition names are used to show an expected range of values for a particular data item.
Once a condition-name has been defined, that particular name can be used instead of testing the data item for a specific value or range of values.
Take the following definition in a program's working-storage section:. With COBOL'85 it is now possible to set a condition by referring to the name instead of the actual value, eg:. As a general rule any program that uses its own set of switches or indicators is badly written.
If it does become necessary to use a separate indicator then please follow these simple guidelines Control can be passed from one point in a program to another by means of the following statements:. These guidelines are extremely flexible, but without additional guidelines the resulting code can be as manageable as a plate of limp spaghetti - please read on for your elucidation and edification. It is common practice in modern programming to split the code into logical sections or modules.
It is usual to plan the structure of a program at the design stage before writing any code, in order to produce a structure similar to that shown in Figure Each box represents a separate module, and where two boxes are joined together it indicates that the box at the lower level is PERFORMed by the box at the higher level.
In this particular example it shows that module Q can only be processed by passing control through modules A, D, J, O to Q.
It is possible for any module to be called from more than one higher- level module, and this should be indicated on the chart. If you have a low-level module which can be called from numerous places eg: an error routine it is permissible to leave it out of the chart completely, as it does nothing but complicate the overall picture.
It should be emphasised that only generalised routines which are common to ALL programs should be regarded as transparent - those which perform a function peculiar to individual programs must appear on the module hierarchy.
It is common practice to give each module some sort of mnemonic to denote its position in the module hierarchy, both horizontal and vertical. In the example given in section 5. It is common sense when coding the procedure division to place the sections in mnemonic sequence - this makes it easier to find your way through the listing.
In method b this means that each leg within the program structure forms a contiguous block, whereas in method a the same sections are spread out all over the place. This is shown more clearly in Figure Using method b it is possible to increase or decrease the number of sections in a particular processing leg without having to rename any other sections in order to maintain the naming sequence. Another advantage of method b is that when a program becomes too large for a single unit and needs to be segmented or split into subprograms it is easy to identify which modules are logically related and therefore eligible for separation.
Compare those modules marked above in method b with the corresponding modules from method a. In a large, complex program with many modules method b may produce mnemonics which are large and cumbersome - how can this be overcome? Common sense to the rescue - identify a sub-function with a large number of modules and start naming them using a different letter from the alphabet, as shown in Figure For a sorted report which has a large number of control breaks it is acceptable to introduce a number into the mnemonic, and to increment this number for each lower level instead of increasing the length of the mnemonic by adding another character.
This would produce a structure chart something like the one in Figure With this method all the processing for a particular sort level would be held in contiguous sections as the sequence would be as follows Some standards have a rule that if a section has more than one parent ie: can be called from more than one section at a higher level then it should be allocated a prefix which represents a general-purpose routine, usually at the bottom end of the alphabet eg: X, Y or Z.
This is fine if it is a small section with limited processing, but what if it is just the start of a significant piece of coding? Take the following example - A database is comprised of customers who are grouped into countries, which in turn are grouped into regions.
A program processes the details for customers at the end of each month, but the selection criteria can be one of the following:. Notice that the selection processing is handled by modules which have the "C" prefix, while the actual customer processing regardless of the selection method has a separate prefix.
This makes tracing your way through the source code a lot easier, which is more important than conforming to inflexible rules with their artificial restraints. This is where a lot of uneducated programmers come unstuck! There are some basic guidelines which can be applied in order to make the code more readable and easier to maintain.
These are:. This example, however, is rapidly approaching the stage at which it becomes too unwieldy to be maintainable. Don't be afraid to split a complex condition into its component parts, even if it involves the use of the GO TO statement.
Don't try to prove how clever you can be - keep it simple and straightforward. This guideline then avoids the possibility that someone may split the paragraph in two, thereby causing the PERFORM to terminate at the new paragraph name.
As there is usually nothing but comments between the section name and the next paragraph it means that no code will actually be executed by that PERFORM statement. Collectives on Stack Overflow. Learn more. Asked 9 years, 11 months ago. Active 5 years, 8 months ago. Viewed 6k times. Improve this question. Vladimir F The code is likely Fortran 90 or newer, not Add a comment. Active Oldest Votes. Improve this answer. Joey k 80 80 gold badges silver badges bronze badges. Joe Zitzelberger Joe Zitzelberger 4, 2 2 gold badges 26 26 silver badges 40 40 bronze badges.
Indeed you are correct. The whole idea of sequence numbers was so that if you dropped your deck on the floor, you could put it in the card sorter and get it back in order. No need for comments: the label if thought out properly tells you why you are going there. Mimicing Fortran, they have their own area so that they stand out and are easy to find also helps if they are in numerical order.
It's hard to explain without teaching what it was like in early days. Until you try writing a COBOL compiler for such an environment, understanding how formatting rules can help the compiler is difficult. Show 6 more comments. The Overflow Blog. Stack Gives Back Safety in numbers: crowdsourcing data on nefarious IP addresses.
Featured on Meta.
0コメント