Sandrila Ltd

Assembly language Coding Standard

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:
  1. project name
  2. program name
  3. CPU type
  4. module name
  5. file name
  6. author's name
  7. creation date
  8. purpose
  9. 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:
  1. a meaningful name
  2. 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:
  1. the procedure name
  2. purpose
  3. input data
  4. output data
  5. 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 8th February 2012