FORTH CODING RULES

The following text is hereby given to the public domain for non-commercial use by all programming with Forth. Non-commercial for the purposes of this document shall mean not for profit reproduction of this text. Commercial organizations may use this text as the basis of their own coding procedures provided they do not then sell such procedures outside their own organizations.

As promised I am posting the Coding Rules, which have been modified from my own company standard and with some modifications as applied to a recent European Contract. The rules have been further edited to address a couple more specific issues. The stack picture information is configured in such a manner that automated tools can generate glossary entries. These stack picture formats will require some additional words to be defined in systems if they are used in source code. They are:

I shall, as soon as I am able, post some code, which will give an idea of how the Glossary generation Tool was intended to work. I am writing it at present (one of those jobs I intended to do for a long time now).

TABLE OF CONTENTS

1.  INTRODUCTION

The aim of this standard is to make the task of reviewing and certifying software easier. In achieving the aims of this standard, certain styles of software source layout, programming and commenting style are mandated.

2.  SCOPE

3.  REFERENCE DOCUMENTS

1. ANS X3.215 "Information Systems - Programming Language - Forth" 1994
2. ISO/IEC 15145 "Information Technology - Programming Languages - FORTH" (=ISO/IEC DIS 15145:1995) 1995
3. "Thinking Forth" Brodie, Leo. 1984 (ISBN 0-13-917568-7)

4.  GLOSSARY OF TERMS

5.  SOFTWARE STANDARDS APPLICABLE

6.  SOFTWARE LISTING ORGANIZATION

Listings should be structured hierarchically, like a well-written and organized book. Each listing should clearly relate to the specification document from which the requirements are drawn. The author of the software listing shall provide clear aids to the trace-ability of the software to its requirement's specification wherever possible. This shall include glossary entry text, further non-glossary descriptions and references to sections or paragraphs of the specification document.

6.1.  DOCUMENT AUDIT INFORMATION

6.1.1  TITLE BLOCK

6.1.2  INTRODUCTORY OUTLINE

6.1.3  EXPORTS

6.1.4  ENVIRONMENTAL DEPENDENCIES

6.1.5  REVISION HISTORY

6.2.  SOURCE CODE DEFINITION

6.2.1.  INCLUDES

6.2.2.  CONSTANTS AND VARIABLES

6.2.3.  FUNCTIONS

Each function definition is in the form of the following, see also colon definition in reference document 1.

: <name> (S input-stack --- output-stack) (R --- )
         (G descriptive glossary text)
  f1 f2  ( interim stack picture) \ programmers explanatory comment
  .. fn ;

Where:

7.  PROGRAMMING STYLE

7.1.  NAMING CONVENTIONS

7.1.1.  PERMITTED CHARACTERS WITHIN NAMES

!"#$%&’()*+,-./ digits [0-9]:;<=>? @ ALPHA [A-Z] [\]^_‘ alpha [a-z] {|}~

Use of Control Characters or any Graphic Characters outside of the above range within definition names is prohibited.

7.1.2.  NAME CONSTRUCTION

7.2.  DEFINITION LAYOUT

A definition should, ideally, be kept short. In no circumstances shall a definition extend for more than one page (approximately 50 lines of 12_pt text, allowing for header and footer margins) and shall not occupy more than 80 characters in width.

7.2.1.  INDENTING POLICY

7.3.  STRUCTURE

7.4.  DIFFERING ACTIONS DEPENDING ON MODE

: ARRAY
  CREATE (S x-size y-size ---)               \ compiling
  ...... .........
  DOES>  (S x-offset y-offset --- a-addr)    \ executing
  ...... ......... ;

7.5.  STACK EFFECT ARGUMENTS

The effects on the Return Stack shall be indicated when words that affect the Return Stack such as >R, R> and R@ are used.

7.6.  WORDS THAT RETURN DIFFERENT NUMBERS OF ITEMS

: ?RX (S --- char true)    \ character present
      (S --- false)        \ character not present
  ...... ......... ;

7.7.  CONTROL STRUCTURES

7.8.  USE OF LITERAL VALUES AND "MAGIC NUMBERS"

7.9.  GLOSSARY TEXT

7.10.  VARIABLES, CONSTANTS AND VALUES

1. Variables, Constants and Values should be defined local to where they are used the first time.
2. Always initialize a VARIABLE to some value when it is initially declared.
3. For the piece of code, in which a variable or value is used (which may deal with a specific function), create an initialization word for each functional section, doing this will reduce the size of the top-level initialization word and make code management easier.
4. Always perform the top-level initialization with a GO or RUN word.

This way, if parts of the hierarchy are used within several applications then you will not miss any if you change something and create a new variable that will need initialization.

8.  AIDS TO VERIFICATION AND VALIDATION

• Test Scripts
• Checklists
• Pre-validated Test Data
• Random Test Data

9.  CERTIFICATION OF SOFTWARE

Certification is applied in a multi-staged process that examines the resultant code formally in Static and Dynamic testing regimes in accordance with a test script designed to prove compliance. All certification processes, consequently, require deriving the assurances they give about the software from a full and thorough audit trail tracing the design and development process from requirement's specification to final product. For this reason version and change control management systems, manual or automated shall be used to ensure full knowledge of the quality basis for all products.

All comments are welcome.