Use of comments within the software

54-71 Doc PS Rev R
(2) Comment fields within the hardware configuration
may
be used however, care is required when doing so hardware comments should only be used where it is necessary for example, to explain a peculiar hardware arrangement, and
should
not be used for standard hardware configuration (for example, IO cards
shall
retain their default designations applied by TIA Portal.
(3) A Style Guide (SG),
[Ref. 004]
,
will
be provide and
will
give details and examples of block commenting, see § 4.6.5
4.6.4
Provision of documentation for the blocks
(1) Every library module will have a detailed specification that provides (as a minimum) the following
• A technical summary (version, memory usage c)
• A functional overview (abstract or summary)
• A detailed block description
• List of parameters and their purpose
• Data structures used by the module
• Any temporary or local data that maybe used
• Calls to other modules
4.6.5
Common style and methodology within the software
(1) A Style Guide (SG),
[Ref. 004] will
be produced that sets out a series of styles, rules, guidelines and general good practices that produces software that is readable, easy to understand and consistent in appearance and approach.

Doc PS Rev R 55-71
(2) The Style Guide
will
do the following
1 Assign rules for block numbering and associations
2 Establish naming conventions for
• Programmable block names (FC, FB and OB)
• Data blocks and instance data blocks (DB and iDB)
• User data types (UDT)
• Block parameter names
• Local variables
• Tag (symbolic) names
• Data block variables
3 Block header conventions (block title and comments)
4 Common network assignments
5 Establish practices for structuring comments
• Titles, headings and subtitles
• Required and common contents
• Tables, equations and figures
• Spellchecking and accuracy
6 Demonstrate how to comment networks within a block
7 Demonstrate how to comment data blocks
8 Apply consistent block properties