INSE - Lecture 16  Documentation  Configuration Management  Program Support Environments  Choice of Programming Language

Documentation

Purpose  Documentation should tell us about the thing being documented … ...not about the person who wrote it!  (But it often does … )

Audiences  various audiences –consequently … »different kinds of document »different styles.

The right level of document...  Fit the vocabulary & complexity of a document to it ’ s audience:  use the reader ’ s jargon - –computing jargon for internal documents; –application jargon for user documents;  clever words & phrasing for clever users (only!)  fit the purpose of the text - e.g. - –intro text should avoid fine detail (but repeat key points from multiple viewpoints); –reference text should include every significant point (once and once only).

Organize the maintenance docs:

MoD JSP188 doc tn. structure 1/ basic outline & system structure, breakdown; s/w for each facility; supporting info; 2/ functional description of each task & data area; timing info; 3/ functional description of each process & data structure; 4/ code, test criteria, supports such as location of firmware.

Documentation standards  Company “ look and feel ” rules;  checklists to promote completeness;  consistency rules when there are multiple authors.  Such standards can vary enormously - –it ’ s more important to have a reasonable standard than exactly what it says … –but the documenter needs to be flexible.

Documentation tools  word processors;  index generators;  systems for graphic display of design descriptions;  cross-referencers and other code-analysis tools; ...

Configuration Management

Problem: Keeping track of all the requirements documents specification documents design documents source files object files test drivers test data debugging records … is a major task in a large project......which gets worse when each of those exists in many versions and variants...

Definitions:  A version may be replaced by a later version;  A variant may be one of many parallel variants, all being "the latest version of that variant".  Large project => usually multiple versions & variants of each software component (maybe hardware components also).  One version/variant may depend on certain versions/variants of other components.

So...  this is a major administration problem in large projects;  there are management issues, but more than that …  … we need something to help us keep track of it all.  Which leads us to...

Program Support Environments

PSE = big brother of an IDE  A PSE is an integrated workbench of tools for programmers and their management  It also is a “ database ” of all of  the documents of a project = specs, design docs, code, test plans, test records, debugging records … etc. …  the audit trails and  the dependencies between the documents.

Programmers view of a PSE  design tools;  compiler(s)  editors(s)  linker(s)  tools to manipulate object files  generalized test harnesses  debugger(s)  source-manipulation tools: –cross-referencers –profilers –indenters –?program provers  documentation tools  programs to detect portability problems with communication between all the tools ….

Team-leader ’ s view A database that  holds all the project documents;  cross-indexes them;  audit-trails them;  helps in configuration management;  helps to mile-stone the progress of the project;  reports symptoms of team-members who may be in trouble; ...

The PSE interface  A single PSE may be hosted on multiple platforms, so …  the project is platform-independent;  the staff are platform-independent (I.e. can move between hardware & O.S.s with minimal retraining.

Choosing an appropriate programming language for the project Issues:  consequences of the choice;  modular languages.

Consequences  Some languages are good for programs that need to be “ close to the hardware ” ;  Some languages are good for big programs;  Some for high-reliability programs;  Some are good for evolutionary development;  Some are good for quickly-written small programs …  No language is good for all of those –they are conflicting objectives.

SO A CHOICE IS NEEDED...  … for each project;  … sometimes, different choices for different parts of a single project. 1/ to make that choice prudently, you need moderate familiarity with multiple languages; 2/ and then do make that choice –don ’ t just “ use what we used last time; –run any re-training your choice demands.

Modular languages (incl.. OO)  Up to 100 lines (or less) - programmer can hold everything in foreground memory –up to 50 lines/day d 3 is common;  Up to 10,000 lines (or less) - programmer can hold everything in background memory –up to 10 lines/day d 3 is common;  But in modular languages, only interfaces need be known –up to 20 to 40 lines/day d 3 is common.

Prejudices  foolish!

After this lecture - documentation  Look at other people's documentation –analyze what are the good features and bad (or missing) features; –analyze how well it fits the need of the audience;  Aim to do better yourself!

After this lecture – CM & language  Be prepared for the extra organizing needed for large projects;  Use sensible tools to keep track of size.  For all projects, make a sensible and well-timed choice of language(s) to use.

© C Lester