TOPS20 CodingStd Mar83

This document outlines the TOPS20 Coding Standards and Conventions for machine language (MACRO assembler) source code, particularly relevant for monitor development.

Key areas covered include:

1. Statement Formatting: Detailed rules for indentation, tab stops, field placement (TAG, OPCODE, AC, @ADDR(X)), and comment alignment to ensure consistency and readability.
2. Comments: Emphasis on extensive and meaningful comments that explain the logical procedure and why actions are taken, rather than just the obvious instruction function. Guidelines for placement (same line, standalone), formatting, and discouragement of irrelevant comments.
3. Listing Pages: Standards for organizing source files into pages using formfeeds, with major modules and subroutines ideally starting on new pages, and avoiding control flow that crosses listing page boundaries.
4. Macros: Preference for monitor-wide, general-purpose macros over localized ones. Conventions for defining and calling macros, including argument handling and use of angle brackets.
5. Conditionals: Indentation rules for assembler conditionals (IFE/IFN) and placement of their terminating angle brackets.
6. Instruction Mnemonics: Requirement to use standard PDP-10 instruction mnemonics without abbreviations, and to define useful, function-related mnemonics.
7. Variables and Structures: Recommendation to use MACSYM facilities for stack and data structures, discouraging explicit PUSH/POP or direct stack referencing. Guidelines for referencing fields (LOAD/STOR) and defining flags (DEFSTR, MSKSTR).
8. JSYS Calls: Detailed conventions for monitor-call JSYSes, including AC preservation, specific return types (success/error), use of MCENT for entry points, and handling error codes.
9. Subroutine Calling: Strict AC allocation conventions for internal monitor routines (arguments, preserved, temporary ACs). Defines standard call and return macros (CALL, RET, RETSKP, BLCAL) and their usage.
10. AC Definitions: Specific mnemonic assignments for various Accumulators (ACs) and rules for their use, including macros for AC saving/restoring (SAVEAC, SAVET, etc.) and defining special-purpose ACs (DEFAC).
11. Subroutine Documentation: A suggested format for documenting JSYS and subroutine calling sequences, including arguments, call instruction, and return conditions/values.
12. Code Structure: Encourages modular code using subroutines and promotes block structure macros (e.g., IFSKP, DO/ENDDO) for control flow over multi-line literals, emphasizing readability and maintainability. Specific rules for multi-line literals and branch conventions (jumps to tags, avoiding "global" jumps).
13. Numbers: All parameters, bit definitions, and codes should be defined mnemonically, avoiding literal numbers in in-line code.

An Appendix A addresses "Living in an Imperfect World," providing guidance for integrating new, compliant code with existing, non-compliant code, particularly concerning AC mnemonics and stack handling.