Parnas and Clement 86 Parnas and Clements: A Rational Design Process: How and Why to Fake It Presented by:Jeremy Bowers, Alireza Namvar IEEE TSE, vol SE-12, no. 2, Feb The Goal of Software Software Engineering: A Rational Design Process What is a rational agent? –Considers all choices thoroughly and correctly –Perfectly documents all results Sounds great, but…

Parnas and Clement 86 There Is No Rational Agent Lots of reasons: –Customers don’t know what they want, –don’t know everything we need in advance, –we’re only human, –external change, –preconceived notions, –economic limitations… –the list goes on We abandon “rational” design...

Parnas and Clement 86 Why Document? Requirements: User Developer communication, estimation, turnover insurance, establishing desired behavior Module: Work assignments, cross-module- implementer communication, module connection overview Future: Maintainers need a way to learn the system Others, too

Parnas and Clement 86 What’s Wrong With Most Documentation? Poor Organization (mostly “stream of consciousness” or “stream of execution”) –Both nearly impossible to find anything when you look for something Boring prose Confusing/inconsistent terminology Myopic viewpoint (too close to system when written)... wouldn’t it be nice to have the “rational” documentation?

Parnas and Clement 86 Fake It! Imagine yourself as the ideal agent, and write the documentation you would have produced Design the documentation –Separation of concerns: One system aspect for one section, no more, no less Document what is important, with the addition of rejected design decisions Justification: Even Mathematics, the very definition of “rational”, works this way: Results preferred over precise history of an idea

Parnas and Clement 86 Conclusions Result: Useful documentation that can be produced in the real world Unlike other papers presented, these ideas are still revolutionary –Unfortunately, few people do this. (In fact, people are often shocked if you do.) Tells us what we want, but not how to get it

Berry, Daudjee, et al Related 1: User’s Manual as Requirements Specification Berry, Daudjee, et al. May 2001 Summary: The desirable properties of a users manual are the same as the desirable properties of a requirements specification. So write the Requirements Specification in the form of a User’s Manual

Berry, Daudjee, et al What Properties? Requirements elicitation Communication –Client can understand user’s manuals where they may not understand other standard requirements documents –Programmers can see exactly what the requirements are calling for Validation –Customer’s ideas versus designer’s ideas –Code versus features

Berry, Daudjee, et al Why User’s Manual? To write one, one must have: –A complete understanding of each use the system will be put to (use cases) We can write one for each type of user, to ensure feature coverage (developer vs. user vs. administrator) Provides scenarios which can be used as test cases Enforces user-centered design (can’t write manual to the developers) Exposes ambiguities

Welsh and Han 94 Related 2: Software Documents: Concepts and Tools Jim Welsh, Jun Han in Software - Concepts and Tools (vo15, no. 1, 1994) Summary: all results of the software engineering process can be considered as documents. Source Code: a carefully specified formal document that can be executed by a computer.

Welsh and Han 94 Ideal Development Environment Set of Documents focusing on required features. Set of Tools help us maintain the documents (i.e. consistency across versions): –starting with the loosest, informal specifications. –moving toward fully formal specifications. –ending up with actual source code (literate program)

Welsh and Han 94

Parnas and Clement 86

Welsh and Han 94 Tools: Rational Assistants verification of code –tie together the original specification, the formal specification, and the actual code. –improve the ease of formally validating code. Improve level of connectivity –automated consistency checks: e.g. propagate a variable name change across all code. –analyze certain changes.

Welsh and Han 94 Extending Parnas and Clements’ work A concrete way to achieve the goals Parnas and Clements lay out. By improving our tools, we improve our ability to create coherent documents. –contain all of the information we may be interested. –from the start through to the finish. If the proposed "Software Documents" existed, it would be much easier to produce "Rational Documentation."

J. Lind 2000 Related 3: A Development Method for Multiagent Systems J. Lind 2000 Summary: a pragmatic process model for the development of multiagent systems based on the combination of standard SE techniques using 7 views. The approach applied and refined successfully in various industrial research projects.

J. Lind 2000 MASSIVE view MASSIVE: MultiAgent SystemS Iterative View Engineering

J. Lind 2000 View-oriented Modeling? “View" is a projection of the root model of the system with only a certain type of information in it. –Projection: is analogous with geometric projection of multi-dimensional objects into lower dimensions. A “Model” for the creation of multiagent systems based on the idea of creating and using seven "views" on the system.

J. Lind 2000 Iterative View Engineering How to create the views and models? Combines: Roundtrip Engineering (Balzert 98) Iterative Enhancement (Basili and Turner 75) Using IE as a repeated subprocess to extend RE –Adding IE steps to the creation of the model, the implementation –Adding trips around the whole process

J. Lind 2000 Extending Parnas and Clements’ work adding to the corpus of work on abstract documentation processes. using the observations Parnas and Clements made about rational design processes. –“any specification is initially incomplete” –Parnas and Clements provided useful ideas for the difficult problem of developing documentation, and software.

Didrich Klein 1996 Uncited: A Pragmatic Approach to Software Documentation Klaus Didrich, Torsten Klein 1996 Summary: The author extends Literate Programming to work in more situations then traditional Literate Program

Didrich, Klein 1996 Quick Sidebar: What is Literate Programming? Developed by Knuth in his paper “Literate Programming”, The Computer Journal, 27(2):97-111, 1984 Principle: Focus on documentation over code, write both in same file Uses a tool to construct source code files from the doc/code hybrid files

Didrich Klein 1996 Dosfop Diagram

Didrich Klein 1996 Problems A language on top of a language increases complexity and learning time Languages have changed –Need for code re-ordering reduced by increased granularity of OO and functional programming –More real programming modules work across multiple files, which original Literate Programming specs handled poorly

Didrich Klein 1996 Why Should This Paper Cite Parnas and Clements’ work? It must be possible to integrate quick-and- dirty code and only later document it This is a way of faking a rational design process