top - download
⟦b19cf0792⟧ Wang Wps File
Length: 6896 (0x1af0)
Types: Wang Wps File
Notes: Source Code Layout Std.
Names: »0359A «
Derivation
└─⟦1304ed705⟧ Bits:30006073 8" Wang WCS floppy, CR 0030A
└─ ⟦this⟧ »0359A «
WangText
…02…SD/STD/014
…02…SVO/801202…02……02…
SOURCE CODE LAYOUT STANDARD
…02……02…CAMPS
1 S̲C̲O̲P̲E̲ ̲A̲N̲D̲ ̲P̲U̲R̲P̲O̲S̲E̲
This standard is applicable to all source programs
coded in PASCAL, SWELL, and other languages with a
similar structure.
The purpose of the standard is to ensure that all source
code is printed in a readable format and contains sufficient
information.
2 H̲E̲A̲D̲E̲R̲
2.1 G̲E̲N̲E̲R̲A̲L̲
All software modules shall contain a header in the
format specified below in which all information necessary
to identify and control the module can be found.
Figure 1 shows the format with lettering to identify
the fields described in the following.
2.2 O̲R̲I̲G̲I̲N̲ ̲S̲T̲A̲T̲E̲M̲E̲N̲T̲
Together with the origin statement enter the name of
the customer in field a). If the module is not produced
for a specific customer, enter a description of the
modules status e.g. "for internal use" or "for general
use".
2.3 M̲O̲D̲U̲L̲E̲ ̲I̲D̲E̲N̲T̲I̲T̲Y̲
In order to identify the module and its place within
a system, enter the following fields:
b) name of project under which the module was developed.
c) name of subsystem within which the module belongs
(if applicable).
d) name of package within which the module belongs
(if applicable).
e) the name of the module.
f) The modules configuration identification number.
2.4 M̲O̲D̲U̲L̲E̲ ̲D̲A̲T̲A̲
Additional data concerning the modules is entered in
the following fields:
g) Name of programmer. If the responsibility of the
module is turned over to another person during
the development, his name shall be added after
the original. Names shall only be deleted if major
changes remove the part of the module which the
person is responsible for.
h) Release number (see section 3).
i) Date of latest release.
j) The programming language used.
k) The operating system necessary to execute the module.
2.5 S̲P̲E̲C̲I̲F̲I̲C̲A̲T̲I̲O̲N̲S̲
Enter in these fields reference to the documentation
associated with the module for each document enter:
Identification number, Title, Issue number, and issue
date.
2.6 I̲N̲T̲E̲R̲F̲A̲C̲E̲S̲
Make an entry in this part for each other unit the
module interfaces directly with. Each entry shall
contain: the name of the unit and the type of interface
e.g., "procedure call" or "interprocess messages".
2.7 M̲E̲R̲G̲E̲ ̲F̲I̲L̲E̲S̲
Enter the names of all files containing sub-modules
which must be included during compilation.
2.8 C̲H̲A̲N̲G̲E̲ ̲R̲E̲C̲O̲R̲D̲
The Change record shall contain all information necessary
to trace the development history of the module since
its first release (see section 3 for definition of
change/release). For each change enter:
q) Number of change
r) Date of change
s) Initials of programmer implementing the change.
t) A short description of the change or a reference
to documentation containing description.
2.9 F̲U̲N̲C̲T̲I̲O̲N̲A̲L̲ ̲D̲E̲S̲C̲R̲I̲P̲T̲I̲O̲N̲
This part of the header shall contain a short but yet
complete description of the functions performed by
the module.
3 D̲E̲F̲I̲N̲I̲T̲I̲O̲N̲ ̲O̲F̲ ̲C̲H̲A̲N̲G̲E̲ ̲A̲N̲D̲ ̲R̲E̲L̲E̲A̲S̲E̲
3.1 C̲H̲A̲N̲G̲E̲
A change is any small revision of the module performed
after the first release. A change may only affect
one logical area of the module or correct one error
or discrepancy. Changes are numbered consecutively
with integer numbers commencing with number 1.
3.2 R̲E̲L̲E̲A̲S̲E̲
A Release takes place every time a new version of the
module is handed over from the programmer responsible
for the development to its future users. These may
be the final user, an integration team or any other
organization who utilizes the module in any way. Releases
shall be numbered by consecutive integer numbers commencing
with number 1.
4 B̲O̲D̲Y̲ ̲L̲A̲Y̲O̲U̲T̲
In order to enhance readability of a listing of source
code, the "body" of the module shall be formatted in
accordance with the rules given in the following paragraphs.
4.1 L̲I̲N̲E̲S̲ ̲A̲N̲D̲ ̲C̲O̲L̲U̲M̲N̲S̲
The code shall be printed with no more than one statement
per line. All statement belonging to the same block
level (see para. 4.3 and 4.4) shall start in the same
column.
4.2 S̲E̲C̲T̲I̲O̲N̲I̲N̲G̲ ̲O̲F̲ ̲C̲O̲D̲E̲
a) Paragraphs.
The code shall be divided into "paragraphs" consisting
of a few logically closely related statements.
The paragraphs shall be separated by one blank
line.
The size of paragraphs shall typically be from
1 to 10 statements.
b) Sections.
A group of closely related paragraphs shall be
collected into a section. Sections shall be separated
by a blank line, a line of hyphens, and a blank
line.
If appropriate, the section shall be given a title
written as a comment just after the separation
preceeding the section.
The size of a section shall typically be 10 to
50 statements with 100 as an absolute maximum (see
fig. 2).
4.3 B̲E̲G̲I̲N̲-̲E̲N̲D̲
The keyword "begin" and the corresponding "End" surrounding
a compound statement shall always be printed beginning
in the same column.
The statements between the keywords shall all be indented
3 print positions relative to the keywords.
The outermost set of begin/end of a program shall be
printed in column 1 (see fig. 2).
4.4 I̲F̲-̲T̲H̲E̲N̲-̲E̲L̲S̲E̲
The keywords of an if-then-else statement shall always
start in the same column (see fig. 2).
5 C̲O̲M̲M̲E̲N̲T̲S̲
5.1 G̲E̲N̲E̲R̲A̲L̲
All code shall be supplied with comments written in
clear English language.
The number of comments shall be sufficient to give
a person with general software knowledge, but without
specific knowledge of the used programming language,
an understanding of the detailed functions of the module.
5.2 C̲O̲M̲M̲E̲N̲T̲ ̲V̲O̲L̲U̲M̲E̲
As a general rule, there shall be one comment for each
paragraph (as defined in para. 4.2 a), with approximately
the same number of words as the paragraph.
5.3 C̲O̲R̲R̲E̲S̲P̲O̲N̲D̲A̲N̲C̲E̲ ̲T̲O̲ ̲S̲P̲E̲C̲I̲F̲I̲C̲A̲T̲I̲O̲N̲
To the extent possible, the comments shall be direct
copies of the corresponding description of the modules
functions in the design specification.
Where a direct copy is not feasible, the comments phrasing,
size, and placing shall give as close a correspondance
as possible to the description in the specification.
5.4 F̲O̲R̲M̲A̲T̲ ̲O̲F̲ ̲C̲O̲M̲M̲E̲N̲T̲
a) The comments shall be placed in front of the statements
to which they correspond.
b) The comment text shall be printed, started in column
36 of each line and be allowed to fill the rest
of the line.
c) Each comment shall be headed by a line of hyphens
also starting in column 36 (see fig. 2).
d) The comment delimiter shall be placed in column
36 of the comment line.
