MULTICS TECHNICAL BULLETIN                                MTB-655

  To:       MTB Distribution

  From:     Gary C. Dixon

  Date:     May 7, 1984

  Subject:  Multics Software Development Guide:  An Outline

  This  MTB  proposes  that  a  new  manual,  the  Multics Software
  Development Guide (or Dev Guide  for short) be written to replace
  the  current  Multics  Standards  SDN  (Order  No.   AN82).   The
  audience  for  the new  manual  are people  writing  software for
  installation in the Multics System  Libraries.  Its purpose is to
  document  standards   and  techniques  for   developing  correct,
  efficient, easy-to-use, easy-to-maintain software for Multics.

  The MTB proposes that the Dev  Guide be drafted by members of the
  Multics  Standards  and  Techniques  Committee  (MSTC)  and other
  interested individuals; and that it will be edited by a member of
  the documentation  unit to unite  the individual sections  of the
  manual  into  a  coherent  whole.  The  manual  will  be reviewed
  several times  as it is  being written to give  everyone who does
  system programming work on Multics a chance to participate in the
  standards development process.

  The MTB is being written  by the Multics Standards and Techniques
  Committee (MSTC) to  gain wider review of their  proposed plan to
  rewrite the current  Standards SDN.  You are asked  to review and
  comment upon the proposals.  Comments should be entered via forum
  in:

     Forum Meeting:  >udd>m>meetings>propose_standards (pstd)
                     (currently a version 1 forum meeting)
            System:  M
          Chairman:  GDixon.Multics
                                                                    |
  Change bars  are used below  to indicate differences  between the |
  published version of  this MTB and the final  draft version which |
  was reviewed in the pstd forum.                                   |

  _________________________________________________________________

  Multics  Project  internal  working  documentation.   Not  to  be
  reproduced or distributed outside the Multics Project.


  MTB-655                                        Dev. Guide Outline

                              CONTENTS

                                                           Page

      1) Multics Standards and Techniques Committee . . .     1
      2) Problems with the Standards SDN  . . . . . . . .     2
      3) The New Manual . . . . . . . . . . . . . . . . .     3
      4) Procedures for Developing the New Manual . . . .     4
      5) Outline for the New Manual . . . . . . . . . . .     5
      PART I:  INTRODUCTION . . . . . . . . . . . . . . .     8
         Section 1:  Introduction to this Manual  . . . .     8
         Section 2:  The Multics Software Philosophy  . .     8
         Section 3:  The Software Development Process . .     8
         Section 4:  Project and Release Planning . . . .     9
         Section 5:  Software Quality . . . . . . . . . .     9
      PART II:  GUIDE FOR DEVELOPING PARTICULAR TYPES OF
       PROGRAMS . . . . . . . . . . . . . . . . . . . . .    10
         Section 6:  Commands and Active Functions  . . .    10
         Section 7:  Interactive Subsystems . . . . . . .    11
         Section 8:  ssu_ Requests and Active Requests  .    11
         Section 9:  Interactive Display Programs . . . .    12
         Section 10:  Other Subroutines . . . . . . . . .    12
         Section 11:  Exec_coms, Ted_coms, Teco_coms,
          etc.  . . . . . . . . . . . . . . . . . . . . .    12
      PART III:  GUIDE FOR SPECIFIC ASPECTS OF SOFTWARE
       DEVELOPMENT  . . . . . . . . . . . . . . . . . . .    14
         Section 12:  Program Attributes and Program
          Structure . . . . . . . . . . . . . . . . . . .    14
         Section 13:  Naming Conventions  . . . . . . . .    15
         Section 14:  Management of Data  . . . . . . . .    15
         Section 15:  Handling Errors, Conditions and
          Other Events  . . . . . . . . . . . . . . . . .    16
         Section 16:  PL/I Efficiency Techniques  . . . .    17
         Section 17:  Guidelines for Assembly Language
          Programming (ALM) . . . . . . . . . . . . . . .    17
         Section 18:  Methods of Improving Quality  . . .    18
         Section 19:  Online Info Segment Documentation .    18
         Section 20:  Documentation in Manuals  . . . . .    19
      PART IV:  SPECIAL PROGRAMMING ENVIRONMENTS  . . . .    20
         Section 21:  Techniques and Standards for
          Writing I/O Modules . . . . . . . . . . . . . .    20
         Section 22:  Techniques for Writing Translators     20
         Section 23:  Techniques for Writing Gates and
          Inner-Ring Programs . . . . . . . . . . . . . .    20


  Dev. Guide Outline                                        MTB-655

                           CONTENTS (cont)

                                                           Page

         Section 24:  Techniques and Standards for
          Hardcore Supervisor Programs  . . . . . . . . .    21
      APPENDICES: . . . . . . . . . . . . . . . . . . . .    21
         Appendix A:  Table of Registered Names . . . . .    21
         Appendix B:  System Databases  . . . . . . . . .    21


  Dev. Guide Outline                                        MTB-655

  1) MULTICS STANDARDS AND TECHNIQUES COMMITTEE

  The Multics Standards and  Techniques Committee (MSTC) is charged
  with  revising  and  maintaining  the  programming  standards and
  techniques used in Multics system software.(1)  The standards are
  currently  maintained  and  documented  in  the  Standards System
  Designers' Notebook (Standards SDN, Order No.  AN82-00).

  The  committee was  created late in  1982 to address  the lack of
  software  development standards  for Multics.   The Standards SDN
  was last published  in June 1980, and most  of the information in
  that  edition  dates back  to  the 1976  MTB-291 by  Ellie Donner
  titled "Draft Programming Standards and Documentation Guide PLM".
  The  committee  found the  manual  extremely out-of-date,  and so
  undertook the task of piecemeal updating of the manual, using the
  procedure outlined in MAB-055.

  That procedure  failed to produce any  significant improvement in
  the Standards SDN.  Only a  few changes were ever proposed, fewer
  still  were voted  upon by  MSTC and  none ever  made it  into an
  addendum for the manual.  The committee withered primarily due to
  the hopelessness  of this futile approach  for piecemeal updating
  of  the  manual.   As a  prime  designer of  the  procedure which
  failed, I take major responsibility for this failure.

  Late in 1983, the increasing corporate and IS emphasis on quality
  coupled  with  the scheduling  and quality  problems we  had with
  MR10.2   forced  management   to  face  the   issue  of  software
  development standards,  once again.  At the  All Multics Managers
  meeting in January, 1984, a variety of task forces were set up to
  review and document current  MDC procedures.  The managers agreed
  that a  usable set of  development standards were  essential.  To
  address this  need, the MSTC was  reactivated.  Current committee
  members are:

        Noah Davids, End User Services Unit
        Gary Dixon, Chairman, Software Support Unit
        Steve Herbst, Language and Database Management Unit
        Chris Jones, Hardcore Unit
        Tom Oke, ACTC
        Gary Palter, Communications and Networking Unit
        Roger Roach, MIT

  _________________________________________________________________

  (1) For details about the origin and charter of the MSTC, see:

       MTB-519, "Documenting System Programming Techiques",
            4/7/81 by Gary Dixon

       MAB-055, "Multics Standards and Techniques Committee",
            8/3/82 by MSTC Members


  MTB-655                                        Dev. Guide Outline

  One  of  the  first steps  of  the reactivated  committee  was to
  consider why the previous committee  had failed.  The main reason
  for the earlier  failure was that the magnitude  of revisions and
  enhancements  needed for  the Standards SDN  was too  large to be
  handled by proposing new standards one-by-one under the procedure
  in MAB-055.

  Based  upon this  analysis, the  committee embarked  upon the new
  approach  of wholesale  revision/rewriting of  the Standards SDN.
  The committee is currently working on this revision now.

  2) PROBLEMS WITH THE STANDARDS SDN

  The  current Standards  SDN suffers  from a  variety of problems.
  Some of the more notable problems are:

  o    There  are  no  standards  covering  use  of  newer software
       facilities (eg, ssu_, video environments).

  o    The manual  is poorly organized, making  it difficult to use
       as  a  reference  guide,  and  difficult  to  determine what
       information  is present  or missing  from the  manual.  Some
       topics  are  discussed  in  several  sections,  rather  than
       grouping similar information together in a single place.

  o    Major  aspects of  software development are  ignored by that
       manual  (eg,  a  description  of  the  software  development
       process  itself,  standards and  techniques for  testing and
       auditing).

  MSTC members  and others who  commented on the  problems with the
  Standards  SDN  (see the  pstd  forum chain  beginning  at [178])
  agreed  that  these  problems   were  insurmountable  within  the
  constraints of the current SDN's organization and stated purpose.
  Therefore, MSTC is  proposing to write an entirely  new manual to
  replace the Standards SDN.


  Dev. Guide Outline                                        MTB-655

  3) THE NEW MANUAL

  On April 3, 1984 MSTC voted during a teleconference to accept the
  following  description for  the manual  to replace  the Standards
  SDN:

       TITLE:
            Multics Software Development Guide

       SHORT NAMES:
            Development Guide or Dev Guide

       AUDIENCE:
            People Writing Software to  be Installed in the Multics
            System Libraries

       PURPOSE:
            To  document  techniques and  standards  for developing
            correct,   efficient,   easy-to-use,   easy-to-maintain
            software in Multics.

  This proposed description of the  Dev Guide was formulated during
  discussions  in the  vote_on_standards (vstd) forum,  and I refer
  the  reader  to  the  vstd forum  chain  beginning  at  [147] for
  details.  The  main points of discussion  were whether the manual
  should  address  a  wider  audience  (such  as  that  proposed by
  Margulies in pstd [194]), and whether the terminology used in the
  statement  of   purpose  was  too   vague  (ie,  terms   such  as
  "standards", "techniques" and "developing  software" are not well
  defined).

  On the audience  issue, MSTC felt that the  committee was created
  solely  to  deal  with a  lack  of standards  for  people writing
  software  to be  installed in  the Multics  System Libraries (eg,
  ACTC, MDC, MIT, third party vendors).  This group might be called
  System  Library Developers.   Therefore, the  committee's efforts
  should be devoted  primarily to the manual which  best serves the
  System Library  Developer audience.  MSTC feels  certain that the
  resulting Dev Guide will benefit other people developing software
  on Multics,  as well.  However,  writing a new manual  to serve a
  far  broader  programming audience  would  be more  difficult and
  time-consuming.   And  such a  broadly-directed manual  would not
  adequately serve the needs of System Library Developers.

  On the  terminology issue, MSTC  felt that is  possible to define
  the  structure   of  the  proposed  Dev   Guide  based  upon  the
  committee's current  understandings of these terms;  and that the
  terms can be more exactly defined in one of the early sections of
  the manual,  which will be  written and agreed upon  early in the
  writing schedule.


  MTB-655                                        Dev. Guide Outline

  4) PROCEDURES FOR DEVELOPING THE NEW MANUAL

  An outline for  the new manual is proposed below  in section 5 of
  this MTB.  The outline shows a manual divided into sections, each
  of  which  deals with  a  particular aspect  of  Multics software
  development.   The following  procedure will be  used in drafting
  these sections, reviewing them,  approving them and incorporating
  them into the new manual.

  Step 1, WRITING:
       The  writing  of  each  section of  the  Dev  Guide  will be
       assigned to one or more people.  Ideas will be gathered from
       the  current  Standards SDN,  from  the standards  that were
       proposed to or adopted by the earlier MSTC, from discussions
       in  the pstd,  vstd and  other Multics  forum meetings, from
       discussions with  other developers, from  current literature
       on Software Engineering and Development, from the results of
       the various All Manager meeting task force teams, etc.

  Step 2, REVIEW:
       Once the first draft of  a section is completed, the authors
       will  make  it  available   for  review  by  announcing  its
       existence in  the pstd forum.  Essentially,  the author will
       be   proposing  the   draft  section  as   a  new  standard.
       Commenting can  then occur in  pstd, via mail,  telephone or
       personal  conversations,  etc.   Based  upon  the  level  of
       comment and controversy, the author may decide to do further
       writing (return to  Step 1), to hold a  formal Design Review
       to resolve  outstanding issues, or to  proceed directly with
       Step 3.

  Step 3, UPDATE AFTER REVIEW:
       The author  will incorporate review comments  into the draft
       section, and announce the final  draft in pstd.  People will
       have a chance to comment in  pstd on this final draft, in an
       effort  to  influence  MSTC  committee  members  approval or
       rejection of the draft section.

  Step 4, VOTING:
       When several  final drafts are available,  the MSTC Chairman
       will call for  individual votes in vstd to  accept or reject
       each  final draft.   Voting will  be based  primarily on the
       technical content  of the draft  (as opposed to  the grammar
       used, etc).   In the case  of rejection, MSTC  will describe
       what changes would make the section acceptable for approval;
       the  author  will  be asked  to  make these  changes  and to
       resubmit the draft for voting again (return to Step 3).


  Dev. Guide Outline                                        MTB-655

  Step 5, EDITING:
       Approved sections of the manual will be given to a Technical
       Writer  to incorporate  into the new  manual.  The Technical
       Writer  will  make sure  proper  grammar is  used,  and will
       format   the   information  according   to   the  formatting
       conventions  established for  the manual  as a  whole.  This
       will help give the manual a coherent flow.(1)                |
                                                                    |
       In  addition,  the author  of  the section  will  submit the |
       approved sections for publication as an MTB.  This will make |
       the  new information  more widely available,  and will allow |
       people to begin informally following the new standard.       |

  Step 6, FINAL VOTING:
       When  editing of  each section  is completed,  the Technical
       Writer will ask for review of  the section in pstd to insure
       that intent of the original information is maintained in the
       edited section.  MSTC will then  vote to approve the editing
       section for  incorporation into the manual,  or will ask the
       Technical  Writer  to  make appropriate  changes  to section
       (return to Step 5).

  Step 7, PUBLICATION:
       When  an  adequate  number  of  edited  sections  have  been
       approved,  the  first revision  of  the new  manual  will be
       published for  use by System Library  Developers and others.
       Subsequently approved  sections will be added  to the manual
       as addenda.

  Step 8, MAINTENANCE:
       We  can  expect  minor   problems,  omissions,  etc  in  the
       published sections of the manual.   These will be dealt with
       by  proposing  changes  to  the manual  in  pstd,  using the
       procedures for approval described  in MAB-055.  This ongoing
       maintenance process will become the steady-state duty of the
       MSTC  once  all  sections  of   the  new  manual  have  been
       published.

  _________________________________________________________________

  (1)       The formatting conventions for the manual have not been
            established yet.  Part of MSTC's  job in the next month
            or so will be to  set these formatting conventions.  We
            feel  such  conventions are  an essential  mechanism in
            clearly  distinguishing   between  recommendations  and
            required  standards.   They  will  also  be  helpful in
            insuring    that   the    manual   discusses    why   a
            recommendation/standard  has  been   set,  as  well  as
            defining what it is.


  MTB-655                                        Dev. Guide Outline

  5) OUTLINE FOR THE NEW MANUAL

  This section  describes the outline  for the Dev Guide,  as it is
  now  envisioned.   The  guide  is divided  into  four  parts:  an
  overview of software development; standards for specific types of
  programs;  standards  for  specific aspects  of  programming, and
  standards  for  special programming  environments.  Each  part is
  composed of several sections, where  each section covers a single
  topic.

  The outline  below describes the  titles for each  major part and
  section of the manual.  After the top-level outline, each part or
  section is described in more detail, including:  a title; a brief
  description of the content of  the part or section; some possible
  major paragraph  headings for the  sections; and the  name of the
  person or persons currently assigned to write the section.


  Dev. Guide Outline                                        MTB-655

                          TOP-LEVEL OUTLINE

  PART I:           INTRODUCTION
    Section 1:        Introduction to this Manual
    Section 2:        The Multics Software Philosophy
    Section 3:        The Software Development Process
    Section 4:        Project and Release Planning
    Section 5:        Software Quality

  PART II:          GUIDE FOR DEVELOPING PARTICULAR TYPES OF
                    PROGRAMS
    Section 6:        Commands and Active Functions
    Section 7:        Interactive Subsystems
    Section 8:        ssu_ Requests and Active Requests
    Section 9:        Interactive Display Programs
    Section 10:       Other Subroutines
    Section 11:       Exec_coms, Ted_coms, Teco_coms, etc.

  PART III:         GUIDE FOR SPECIFIC ASPECTS OF PROGRAM
                    DEVELOPMENT
    Section 12:       Program Attributes and Program Structure
    Section 13:       Naming Conventions
    Section 14:       Management of Data
    Section 15:       Handling Errors, Conditions and Other Events
    Section 16:       PL/I Efficiency Techniques
    Section 17:       Guidelines for Assembly Language Programming
    Section 18:       Methods of Improving Quality
    Section 19:       Online Info Segment Documentation
    Section 20:       Documentation in Manuals

  PART IV:         SPECIAL PROGRAMMING ENVIRONMENTS
    Section 21:       Techniques and Standards for Writing I/O
                       Modules
    Section 22:       Techniques for Writing Translators
    Section 23:       Techniques for Writing Gates and Inner-Ring
                       Programs
    Section 24:       Techniques and Standards for Hardcore
                       Supervisor Programs

  APPENDICES:
    Appendix A:       Table of Registered Names
    Appendix B:       System Databases


  MTB-655                                        Dev. Guide Outline

  PART I:  INTRODUCTION

  The first part of the manual:
    - gives an introduction to the manual itself,
    - describes the Multics software philosophy;
    - describes the software development process;
    - describes how  software releases and  major software projects
      are defined and prepared; and
    - defines major terminology used throughout the manual.

  Section 1:  Introduction to this Manual

       This  section describes  the intent  of the  manual (ie, its
       purpose, intended  audience, organization) and  suggests how
       it should be used (ie,  primer or reference usage).  It also
       describes formatting conventions used throughout the manual,
       and defines two major terms:  standards and techniques.

  WRITERS:  (no one yet assigned)

  PARAGRAPH HEADINGS:
            Purpose of this Manual
              Standards vs.  Techniques
            Organization of the Manual
            Formatting Conventions
            Use as a Primer
            Use as a Reference Guide

  Section 2:  The Multics Software Philosophy

       This  section reviews  major goals  and overall philosophies
       used  in  Multics software.   This would  include philosophy
       statements from early Multics  design papers (eg, ideas from
       Multics:  The First Seven Years by Corbato').  It should also
       include  a  brief  overview  of  system  organization  (ring
       protection, organization  of supervisor, ring 1,  ring 2 and
       user ring environments, etc).

  WRITERS:  (no one assigned yet)

  PARAGRAPH HEADINGS:  (none formulated yet)


  Dev. Guide Outline                                        MTB-655

  Section 3:  The Software Development Process

       This  section  describes  the  overall  process  of software
       development,  and  defines  the  major  terminology  of  the
       software development process.  It  is based upon the results
       of Greg Baryza's Software Development Process Task Team, and
       Frank Martinson's Installation Process Task Team.

  WRITERS:  Task Team Reports edited by Steve Herbst.

  PARAGRAPH HEADINGS:
            Problem Analysis
            Designing a Solution
            Design Review
            Design Approval
            Implementation
            Testing
            Auditing
            Installation
            Maintenance
              Error Reporting via TRs and Error Lists

  Section 4:  Project and Release Planning

       This  section   describes  procedures  for   planning  major
       software development projects, and for integrating a variety
       of such projects into a  software release.  It is based upon
       the  results of  Paula Wood's  Project/Release Planning Task
       Team.

  WRITERS:  Task Team Reports, edited by (no one assigned yet).

  PARAGRAPH HEADINGS:  (none known yet)

  Section 5:  Software Quality

       This  section  defines  software quality  using  the Quality
       College  definitions.   It basically  gives  a recap  of the
       material given in LCPD's recent Quality College classes.

  WRITERS:  Gary Dixon

  PARAGRAPH HEADINGS:  (none known yet)


  MTB-655                                        Dev. Guide Outline

  PART II:  GUIDE FOR DEVELOPING PARTICULAR TYPES OF PROGRAMS

  This major part of the  manual describes standards and techniques
  applicable  to  specific  types  of programs.   The  follow major
  program types are considered:

       o    commands and active functions

       o    interactive subsystems

       o    ssu_ requests and active requests

       o    interactive display environments (eg, xmail)

       o    other types of subroutines

       o    exec_coms, ted_coms, teco_coms, etc.

  Each  program type  differs from other  types in  the areas shown
  below.   The  section  describing  each major  program  type will
  highlight these areas of difference.

  1)   method of invocation (eg, by user via command_processor_, or
       by another program)

  2)   interface specification
         - function or subroutine
         - input parameter attributes
         - output parameter attributes
         - method of accessing parameters

  3)   interaction with its caller, and with the user:
         - getting input (eg, command_query_)
         - printing output
         - reporting errors

  4)   documentation
         - documentation for a manual
         - info segments

  5)   other  standards   and  techniques  characteristic   of  one
       particular program type.

       The  sections  in  this  part  of  the  manual  will  try to
       highlight the differences between these major program types,
       as well as discussing standards and techniques which pertain
       to only one of the program types.


  Dev. Guide Outline                                        MTB-655

  Section 6:  Commands and Active Functions

       This  section  will  describe  proper methods  of  writing a
       command, an active function,  and a procedure which operates
       as both a command and an active function.

  WRITERS:  Steve Herbst, Gary Palter

  PARAGRAPH HEADINGS:
       Besides  discussing  the  five  areas  of  difference  which
       distinguish  the various  major program  types, this section
       discusses standards for arguments  and control arguments and
       well as standards for  general argument syntax standards and
       conventions.  Exact headings are yet to be determined.

  Section 7:  Interactive Subsystems

       This  section  will  describe standards  and  techniques for
       interactive  subsystems.  Subsystems  to be  covered include
       those  which use  ssu_ (eg, read_mail,  send_mail, forum) as
       well as those which do not use ssu_ (eg, qedx, ted, probe).

  WRITERS:  Gary Palter

  PARAGRAPH HEADINGS:
       Besides  discussing  the  five  areas  of  difference  which
       distinguish  the various  major program  types, this section
       discusses the following topics:

            Interruptability (eg, quit/pi)
            Recursiveness
            When to use ssu_; when not to
            Standards for use of ssu_, including:
               Standard Requests
               Standard Control Args
               Abbreviation Processing
               Subsystem Exec_coms
               Sample ssu_ Subsystem

  Section 8:  ssu_ Requests and Active Requests

       This section  discusses standards and  techniques for coding
       subsystem requests  and active requests.   While the discuss
       will  briefly  consider   non-ssu_  subsystem  requests,  it
       applies primarily to ssu_ requests and active requests.

  WRITERS:  Gary Palter, Steve Herbst


  MTB-655                                        Dev. Guide Outline

  PARAGRAPH HEADINGS:  The 5 areas of difference, plus:
            Request Naming Conventions (a crossref to Section 13)
            Control Argument Naming Conventions (also a crossref)
            Request Documentation
            Requests which are Subsystems
            Requests Which can be Standalone Invocations

  Section 9:  Interactive Display Programs

       This section discusses standards  and techniques for special
       interactive display subsystems such as xmail and tutorial.

  WRITERS:  Noah Davids

  PARAGRAPH HEADINGS:
            What is an Interactive Display Environment?
            Using Windows
                 window_
                 window_io_
                 Handling of asynchronous output.
            Menus
                 Designing Menus
                 Use of menu_

  Section 10:  Other Subroutines

       This   section  discusses   standards  and   techniques  for
       subroutines.  The  main emphasis is on  interface design and
       argument   standards  (including   standards  for  structure
       arguments), on subroutine  attributes (recursive, reducible,
       etc), on error handling, etc.

  WRITERS:  Steve Herbst

  PARAGRAPH HEADINGS:
       Basically, the five areas of difference.

  Section 11:  Exec_coms, Ted_coms, Teco_coms, etc.

       This   section  discusses   standards  and   techniques  for
       exec_coms, ted_coms, teco_coms and the  like which are to be
       installed in the  system.  The main emphasis is  on the user
       interface, handling of errors,  storage of data, commenting,
       documentation, etc.

  WRITERS:  Gary Dixon


  Dev. Guide Outline                                        MTB-655

  PARAGRAPH HEADINGS:
       The  five  areas  of  difference, plus  some  others  as yet
       undetermined.


  MTB-655                                        Dev. Guide Outline

  PART III:  GUIDE FOR SPECIFIC ASPECTS OF SOFTWARE DEVELOPMENT

  This  major section  of the  guide discusses  aspects of software
  development  which  are common  to  all types  of  programs.  The
  intent is  to group programming aspects  common to many different
  types of programs into a single place so the user doesn't have to
  hunt  through  many  sections  of   the  guide  looking  for  all
  information on a particular topic.

  Section 12:  Program Attributes and Program Structure

       This section  describes what attributes  programs must have,
       and how they should be structured.

  WRITERS:  Gary Dixon

  PARAGRAPH HEADINGS:
            General Program Attributes
              Reentrant
              Transparent
              Recursive
              Reducible
              Interruptable
            Program Structure
              General Layout of a Program
                Software Protection Notice
                Change History Comments
                Declarations and Include Files
                Body of the Program
                Ordering of Internal Procedures
              Comments
                Protection Notice and Change History
                Interface Description
                  External Interfaces
                  Internal Procedure Interfaces
                Overview of Algorithm
                Summary of Each Section of Code
                Line-by-Line Comments
                Comments for Declarations
              Program Readability
                Indentation
                Variable Names
                Misuse of Initial Attribute
              Modularity
                Structured Programming and Data Concealing
                Compile Unit Size
                Bound Segments
                  Archiving
                  Binding


  Dev. Guide Outline                                        MTB-655

  Section 13:  Naming Conventions

       This  section  deals  with  the standards  for  naming.  All
       aspects of the naming issue  are covered here rather than in
       other sections.  Other sections  may make crossreferences to
       pertinent naming standards in this section.

  WRITERS:  Roger Roach

  PARAGRAPH HEADINGS:
            Types of Programs
              Commands
              Active Functions
              Subsystem Requests
              Subroutines
              Exec_coms, Ted_coms, etc
            Arguments
            Control Arguments
              Commands and Active Functions
              Subsystem Requests
            Program Source Constructs
              Variable Names
              Structures
              Include Files
            I/O Switches
            Condition Names
              System-defined
              Software-defined
            Storage System Files
              Entryname Suffixes
              Value Segment Variables

  Section 14:  Management of Data

       This  section  discusses  standards and  techniques  for all
       aspects of data storage and management.

  WRITERS:  (no one assigned yet, Lindsey Spratt will collaborate)

  PARAGRAPH HEADINGS:
            How to Store Particular Types of Data
            Temporary Storage
              Use by Storage Scope
                Internal Data Variables
                External Data Variables
                Passing Data between Program Modules
              Use by Storage Class
                Automatic
                Based
                Controlled
                Defined


  MTB-655                                        Dev. Guide Outline

                Parameter
                Static
              Temp Segments
              PL/I Areas
                System-provided
                Application-provided
              Use of Process Directory vs. Temporary Directories
            Permanent Storage System Files
              Read/Only Access to Files     In each of these,
                Segments                  |  cover issues of:
                Archives                  |  initiation,
                MSFs                      |  termination,
              Read/Write Access to Files  >  truncation,
                Segments                  |  bit counts,
                Archives                  |  force_write, etc
                MSFs                     /
              Data Bases
                Lister DBs
                MRDS DBs
                DM Files
              Inner-Ring Files
                Use of inner-ring queues
                Use of mailboxes
              Access by Dynamic Linking
                Reference Names
              Access by Pathnames
                Handling Star and Equals Conventions
                Search Lists
              Access Assumptions
              Access Control
            Per Process or Per System Data Segments
              Access by Dynamic Linking
                Reference Names
              Access by Pathname
                Avoid Building Pathnames into Programs
              Use of create_data_segment
              Use of value segments
|           Access Considerations
|             Discretionary Access
|             Locking for Shared Databases
|             Nondiscretionary Access Considerations (AIM)
|             Access to System Databases and Gates

  Section 15:  Handling Errors, Conditions and Other Events

       This  section  discusses  all  aspects  of  error reporting,
       condition handling, error recovery techniques, etc.


  Dev. Guide Outline                                        MTB-655

  WRITERS:  Matt Pierret, Lindsey Spratt

  PARAGRAPH HEADINGS:
            Events
              Conditions
              Errors
              Status Messages
            Conditions
              Cleanup Handlers
              any_other Handlers
              Other System-defined Conditions
              Programmer-defined Conditions
            Errors
              Types of Errors
                Correctable by User
                Uncorrectable errors (correctable by system
                  programmer; errors which shouldn't occur)
                Impossible Errors (hardware failure)
              Error Reporting Mechanisms
                Communicating with the User
                Quality of Error Messages

  Section 16:  PL/I Efficiency Techniques

       This section recommends techniques for efficient programming
       in PL/I programs.  The intent  is that it will encompass all
       information  in Section  8 of the  current standards manual,
       plus other discussions of efficiency as they are identified.

  WRITERS:  Gary Dixon

  PARAGRAPH HEADINGS:
       Those in Section 8 of the Standards SDN, plus others as they
       are suggested.

  Section 17:  Guidelines for Assembly Language Programming (ALM)

       This section  presents standards and  techniques for writing
       ALM programs.  Besides dealing with general ALM programming,
       the section  specifically covers coding  of transfer vectors
       and coding of gates.

  WRITERS:  Chris Jones


  MTB-655                                        Dev. Guide Outline

  PARAGRAPH HEADINGS:
            When ALM is appropriate
            General ALM Coding Standards and Techniques
              Register Usage
                Assumptions Made by the Assembler
                Variable Naming
              Calling Conventions
              Coding with Macros
            Coding of Error Tables
            Coding of Transfer Vector Procedures
            Coding of Gates

  Section 18:  Methods of Improving Quality

       This  section  describes  the standards  and  techniques for
       improving the quality  of one program or a  set of programs.
       Topics covered include  self-auditing, testing and debugging
       techniques,  metering  and  performance  analysis,  and peer
       review auditing.   Gary Dixon's proposal  for auditing (pstd
       [277]) would be used as source material for this section.

  WRITERS:  Noah Davids

  PARAGRAPH HEADINGS:
            Self-Auditing of Code by the Programmer
            Testing and Debugging Programs
|             Special Support Code for Testing
|               Setting Up a Testing Environment
|               Adding Debugging Code
|               Programming Techniques for Probing
            Metering and Performance Analysis
            Peer Auditing of Code

  Section 19:  Online Info Segment Documentation

       This section describes  standards and formatting conventions
       for info  segments.  Included are  at least 5  kinds of info
       segments:   command/af  info  segs,  subroutine  info  segs,
       general  info  (.gi)  segments, changes  info  segments, and
       known error  info segments (info segments  produced from the
       error lists for distribution to sites).  Also, info segments
       for subsystems are described in this section.

       This section also describes  the various tools available for
       producing    info     segments    (eg,    validate_info_seg,
       input_info_seg, single-sourcing MPM macros, etc).

  WRITERS:
       Jim Batts (presumably with input from Lee Baldwin)


  Dev. Guide Outline                                        MTB-655

  PARAGRAPH HEADINGS:  (none known yet)

  Section 20:  Documentation in Manuals

       This   section  describes   the  standards   and  formatting
       conventions used for Multics manuals.  It will reference all
       pertinent  HIS documentation  standards, and  will refer the
       user  to compose  macros used  to provide  standard formats,
       etc.

       At the  current time, Jim  Batts isn't sure  if this section
       should be  written, or when  we would be ready  to write it.
       Our documentation methods  always seems to be in  a state of
       change, making them difficult to use, much less to document.
       Jim is investigating.

  WRITERS:  probably Jim Batts

  PARAGRAPH HEADINGS:  (none known yet)


  MTB-655                                        Dev. Guide Outline

  PART IV:  SPECIAL PROGRAMMING ENVIRONMENTS

  This major part of the  manual describes additional standards and
  techniques  for programs  which must run  in special environments
  (eg,  hardcore programs),  or for programs  which perform similar
  functions (eg, translators).

  Section 21:  Techniques and Standards for Writing I/O Modules

       This section  describes standards and  techniques for coding
       iox_ I/O  modules.  This section  with primarily be  a cross
       reference  to  the material  in the  MPM Reference  Guide on
       writing I/O modules.  However,  there may also be additional
       standards imposed  on System Library I/O  modules beyond the
       techniques recommended in the Ref Guide.

  WRITERS:  Gary Dixon

  PARAGRAPH HEADINGS:  xref to MPM Ref Guide

  Section 22:  Techniques for Writing Translators

       This section describes standards and techniques for programs
       which  are  translators  (compilers  or  interpreters).  The
       section  includes   a  broad  spectrum   of  material,  from
       discussion   of   simple  translators   written   using  the
       reduction_compiler,    to    use   of    LALR    and   other
       compiler-generation techniques for  more formal translators.
       In addition, it sets  standards for our language translators
       (PL/I, Fortran, Cobol, Pascal, etc).

       Work on  this section will  probably be delayed  until 1985,
       when UC can  allocate man power in their  1985 plan for this
       writing effort.

  WRITERS:  Brian Westcott and UC Personnel

  PARAGRAPH HEADINGS:  (none known yet)

  Section 23:  Techniques for Writing Gates and Inner-Ring Programs

       This section describes techniques  and standards for writing
       inner-ring programs (programs which  operate inside the user
       ring, but outside of ring 0).  Topics will include:  writing
       gates   and   gate  targets,   inner  ring   access  control
       conventions, things which don't work as expected in an inner
       ring (eg, relative pathnames, initial ACLs), etc.

  WRITERS:  Gary Palter


  Dev. Guide Outline                                        MTB-655

  PARAGRAPH HEADINGS:  (none known yet)

  Section 24:  Techniques and Standards for Hardcore Supervisor
  Programs

       This   section  describes   standards  and   techniques  for
       programming  in  the Ring  0  environment, and  also  in the
       Bootload Multics environment.

  WRITERS:  Chris Jones

  PARAGRAPH HEADINGS:  (none known yet)

  APPENDICES:

  The  appendices give  quick-reference to list  of standard items.
  Besides  the  table of  registered  names in  appendix  A, future
  appendices might include a  flowchart of the software development
  process,  a  checklist  for  auditing, etc.   For  now,  only one
  appendix is being proposed.

  Appendix A:  Table of Registered Names

       This appendix lists registered  names for control arguments,
       suffixes,  I/O switches,  conditions, value  variables, etc.
       Associated  with  each name  is a  brief description  of its
       intended  use.   For  control  arguments,  this  description
       includes   the  standard   meaning,  sample   usage,  and  a
       crossreference to other, related control arguments.

  WRITERS:  Steve Herbst, Lee Baldwin

  PARAGRAPH HEADINGS:
            Registered Names
              Control Arguments
              Suffices
              I/O Switch Names
              Condition Names
              Value Segment Variable Names

  Appendix B:  System Databases

       This appendix gives an overview description of major Multics
       system   databases  which   might  be   accessed  by  system
       programmers,   including   information   contained   in  the
       databases, expected access patterns and access requirements.

  WRITERS:  (none assigned yet)


  MTB-655                                        Dev. Guide Outline

  PARAGRAPH HEADINGS:
      I'm not sure how much detail to go into in this appendix,
      or which databases should be covered.  Some possibilities
      are:

            Supervisor Databases
              active_all_rings_data
              dseg
              kst
              pds
              prds
              sys_info
              time_info_
            Administrative Databases
              SAT
              PNT
              URF
              PMF/PDT
              CMF/CDT
            Inner-Ring Databases
              Mail Table
            User-Ring Databases
              Stack
              Combined Linkage Area
                System Free Area
                User Free Area
              RNT
              LOT
              ISOT
              TTF/TTT
              static condition table (SCT)
              value segments