Introduction
Assembly language programming is the lowest level computer language normally used. By it's very nature it can be difficult to write and maintain, both by the author and by anyone maintaining the program, hence a standard for programming style can only assist with both these requirements.
This document describes the preferred standards to be used when designing and writing programs in assembly language. This standard is assembler / language independant whereever possible.
Scope
This standard refers to all assembly language programs, whether for customer delivery or for in-house development and test purposes.
Header
The header area of the program shall consist of at minimum a title block.
Title
The title block shall consist of the following information:
- project name
- program name
- CPU type
- module name
- file name
- author's name
- creation date
- purpose
- target processor
Include Files
After the title block, any include files should be defined. These shall contain global data definitions, constants, I/O port definitions etc. as symbolic references.
Identifiers
All identifiers declared in the program shall have the following attributes:
- a meaningful name
- use of legal seperators to increase readability
Data Declarations
An area of the program source code shall be reserved for data declarations. All declarations shall, where possible and depending on the assembler being used, allow the identifier being declared to be easily distinguished as such e.g. many assemblers allow the use of a ':' after the identifier name. The data declarations shall be divided into two areas, one for global data and one for local data.
Global and Local Data
Data declared in one module and used in another shall be kept seperate from data used purely locally. The declaration that an identifier is global shall be in the same locality as the data declaration.
Where a data item is defined to be global, then the module(s) using this data shall be declared in a comment alongside the global declaration.
A data item shall only be declared to be global where necessary.
External Data
Where a data item is defined to be external, then the module containing the global definition shall be declared in a comment alongside the external declaration.
Data Typing
Assembler is often used by the programmer to compromide the data typing of a high-level language, this is forbidden All data declared in, or used by a program module must follow the same data typing rules as for high level languages, even though the assembler may not detect violations.
Text
Where text is defined in a module, part of the text may consist of non-printable characters, these shall be defined as identifiers or macros i.e. if a text string requires the ASCII escape code then the non-printable code shall be defined typically as:
ESC: EQUATE 1BH
and used in the text string typically as:
HOME_TEXT: DB ESC, '[',0
END_HOME_TEXT: EQUATE $
The length of the text may be calculated by the assembler as:
HOME_TEXT_LENGTH: EQUATE END_HOME_TEXT - HOME_TEXT
Constants
Where a constant is to be used by a program, this constantt shall be defined as an identifier e.g.:
NO_OF_BUFFERS: EQUATE 16
BUFFER_SIZE: EQUATE 256
Procedures
Procedures should not be longer than two sides of listing.
A procedure should perform a single, well defined function.
Procedure Headers
Each procedure within a module shall have a header consisting of the following data:
- the procedure name
- purpose
- input data
- output data
- registers modified
Indentation
A standard indentation method shall be used within a program project, whether this is spaces or tabs does not matter, but mixing the two can cause listings to become untidy and unreadable.
Control Transfer
Transfer of control within a procedure shall only be via JUMP instructions. Indirection within a procedure is forbidden. CALLs to other parts of the procedure are also forbidden.
Transfer of control to other procedures shall be via CALL instructions. Indirection to other procedures is allowed via CALL instructions or vai a well documented simulation of a CALL instruction. Indirect JUMPs to other procedures are forbidden.
Each procedure shall have only one entry and exit point.
Comments
All programs shall contain sufficient comments. These comments shall be correct, both functionally and grammatically.
A useful commenting method is to write a block comment describing the function of the follwing block in psuedo-code. then comment individual lines as required e.g.
; if INPUT_VALUE <= MAX_VALUE then
MOV AX,[BP+2] ; get data off stack
CMP AX,MAX_VALUE ; compare with maximum value
JLE CHECK_MIN ; if OK then go and check minimum
; else flag error
MOV AL,INPUT_FAULT
CALL ERROR
Assembler directives
Macros
The use of in-line macros is allowed for the purpose of reducing very short repetitive blocks of code into a meaningful block. Macros shall not be used to hide otherwise prohibited or dangerous programming constructs.
Macros using the result of a previous macro invocation indirectly are prohibited.
Scope for Code Examination
Files
Location
Number of files
Size of each file
Functional grouping of procedures in each file
Number of procedures in each file
File header
Module name
Module name stated at end of file
Procedures
Size of procedure
Procedure header
Entry
Single
Conditions
Exit
Single
Conditions
Side effects
Registers modified
Global variables modified
Comments
Correct
Sufficient
Assumptions
Global Declarations
Unnecessary
Used by
External Declarations
Unnecessary
Used by
Control Transfer
Conditional
Re-entrant
Recursive
Identifiers
Silly names
Meaningful names
Data Typing
Range checking
>=, <= rather than =
Constants
Include files for constants
'Magic' numbers
Text should not be numeric
Assembler Directives
Origin statements
Let the assembler do the work
Text
ASCII/ANSI where possible
Document I-Stan-001-000 issue 1 29th July 2000
Return to Work Page
Last updated 11 February 2003
