Post on 01-Apr-2015
transcript
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.
System Evaluator: Functional Description
System Evaluator: Functional Description
System Programmer: Installation Document System Operation Doc
System Programmer: Installation Document System Operation Doc
Novice User: Introductory Manual
Novice User: Introductory Manual
Experienced User: Reference Manual
Experienced User: Reference Manual
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 doctn. 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 d3 is common;
Up to 10,000 lines (or less) - programmer can hold everything in background memory– up to 10 lines/day d3 is common;
But in modular languages, only interfaces need be known– up to 20 to 40 lines/day d3 is common.
Prejudices
Ada programmers think that…
C programmers think that…
… C is …
… anarchy
… freedom
… Ada is …
…organization
… bondage
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 1997-2003