A Case Study of an Industry Project

Computer Science, Karlstad University

Eivind J. Nordby, Martin Blom, Anna Brunström

Work Report December 1999

A Case Study of an Industry Project

Eivind J. Nordby, Martin Blom, Anna Brunström {eivind.nordby, martin.blom, anna.brunstrom}@kau.se

This report describes the study of an industrial software-development project during 1999, as seen from a semantic point of view. The project lasted about 6 months, included about 10 persons, and had a medium level of innovation and a high pace. The study was part of an ongoing research project at the department of computer science. It was performed by a researcher while he was participating as a team member in the project. The objective of the study was to gain a better knowledge of how semantic issues are managed in practice and to identify factors that may limit the possibilities to focus on semantics in a development project of this kind. The research group of the researcher is working on a development method with a focus on semantics, and the experiences will be useful for this work.

The semantic modeling done during the project was mostly intuitive, but those parts of the product that were planned semantically had few errors. Design contracts were successfully used in part of the project. Although the project members were not used to working with design contracts, they soon learned to respect them.

Lessons about semantics were learned, regarding as well the management, the work and the product. For management, the main lessons were that semantic planning pays off in terms of high development speed and low error rates and that changes in the specifications occurring during development must be managed. For the project work, the main lessons are that time and effort are saved if clear semantic specifications were given before the implementation and that communication between team members about semantics should be managed. In addition, the theoretical result that strong contracts may be weakened was confirmed. For the product, the main lesson is to adapt the semantics of a module to its intended usage pattern.

iii Contents

1 Introduction...... 1 2 The Framework of the Industry Study...... 3 2.1 Some Terms used in this Report...... 3 2.2 The research context of semantic integrity...... 4 2.3 A Presentation of the Research Project Skutt...... 4 2.3.1 The focus area for Skutt: Semantic descriptions through design contracts 2.3.2 Different views on interfaces 3 The Object of Study...... 6 3.1 Objectives and Functionality of the Product...... 6 3.2 Characteristics of the Product...... 7 3.3 Characteristics of the Project...... 8 3.4 Organization of the Project...... 9 3.4.1 Delegated and synchronized project management 3.4.2 Organization of the work 3.4.3 Simplified process model 4 Observations and Consequences...... 11 4.1 Planning and Management...... 11 4.1.1 The design responsibilities 4.1.2 The organization of the work 4.2 The Project Work...... 12 4.2.1 Thorough MMI definition 4.2.2 Design before implementation of DBI 4.2.3 Focus on contracts in DBI 4.2.4 Iterative development of BLI 4.2.5 Lack of communication 4.2.6 Initial lack of respect for strong contracts 4.2.7 Insufficiency of informal communication 4.3 The Resulting Product...... 14 4.3.1 The Database Interface module (DBI) 4.3.2 The Business Logic Interface module (BLI) 4.3.3 The user interface tier 4.3.4 Design considerations for the open client/server interface 4.3.5 Testing 5 Lessons Learned...... 18 5.1 Planning and Management...... 18 5.1.1 Communicate with the customer 5.1.2 Plan details to avoid errors 5.1.3 Implement changes in the specification throughout the product 5.1.4 Manage the design to avoid misunderstandings 5.1.5 Inform newcomers 5.1.6 Plan for early detection of misunderstandings 5.2 The Project Work...... 20 5.2.1 Plan and document the MMI thoroughly

iv 5.2.2 Use strong contracts for increased client quality 5.2.3 Use strong contracts for increased supplier quality 5.2.4 Actively inform client designers about supplier semantics 5.2.5 Start out with strong contracts 5.2.6 Differentiate between errors and errors 5.3 The Resulting Product...... 21 5.3.1 Match the complexity of an API to its use 5.3.2 Handle client/server interfaces as an open user interface 6 Conclusions and Further Work...... 23 6.1 Planning and Management...... 23 6.2 The Project Work...... 23 6.3 The Resulting Product...... 24 6.4 Further Work...... 24 References...... 25 A Summary of Lessons Learned...... 26 A.1 Planning and management...... 26 A.2 The Project Work...... 26 A.3 The Resulting Product...... 27 B Terms and Abbreviations...... 28

v List of Figures

Figure 3.1-The principal actors for the product and their relationships...... 6 Figure 3.2-The architecture and the principal modules of the product...... 8

vi vii 1 Introduction

This report describes the experiences gathered during the participation of a computer science researcher in an industry project during the spring of 1999. The participation was part of an ongoing research project, called Skutt, at the department of computer science at Karlstad University1. The research in Skutt is focusing on quality issues in software development from a semantic point of view. The objective of the participation was to study how semantic issues are managed in an industrial development project. After the industry project, the experiences will be used in the development of a semantic method during subsequent phases of the Skutt research project. The purpose of the study, therefore, was to try to identify areas where the semantic quality can be increased and to recognize some practical restrictions that should be considered in such a semantic development method. For simplicity, in the rest of this report the research project will most of the time be referred to simply by the name Skutt. Unqualified references to the project should be understood to mean the industry project under study and the product should be read as the product produced during the project. The project was run at Ericsson Infotech AB in Karlstad (EIN), another contributor to the project. In order to gain an inside view of the industry project and its conditions, the researcher performed the industry study while participating in the development team as a designer. Since his time was spent in production, the possibility to observe all the aspects of interest was limited. This of course affects the observations and the conclusions. Conclusions not based on own observations may for instance be based on hearings or qualified assumptions. Reservations will be made where appropriate. The participation in the project should also be as neutral as possible, so the researcher refrained as much as possible from expressing personal opinions on aspects of the project itself. The study of one single project cannot be expected to give a full insight in all the problems a software development team is facing during a project. The study reported here is therefore meant only as a complement to other sources of knowledge, such as literature and personal experience. Three aspects of the project were of interest, namely planning and management, the actual work and the resulting product. The planning and the management of the project are of interest because it settles the framework and the conditions for the work and may thus influence the way semantics is managed. Observing how the actual work was carried out shows how semantic issues are handled in practice during the execution of the project. The resulting product, through various properties, can give information about appropriate approaches and about the success of the work carried out. The rest of this report is structured as follows. Chapter 2 presents the framework of the industry study, starting with the research project Skutt. This chapter also defines most terms used in this report. The definitions are also summarized in Appendix B. Chapter 3 then presents the project where the study took place as well as the product produced during that project. The next three chapters, chapters 4 through 6, are related to the observations made during the project and their consequences. These chapters are structured after the three areas planning and management, work, and resulting product, which are mentioned above. Chapter 4 presents the main observations relevant to the objective of the study and their consequences in the project. Chapter 5 draws some lessons that can be learned from these observations. Finally, Chapter 6 summarizes the conclusions from the preceding chapters and indicates some areas for further study.

1 Skutt is also supported by NUTEK, the Swedish National Board for Industrial and Technical Development. 1 Appendix A summarizes the lessons learned from Chapter 5 and Appendix B, is a collection of most terms, abbreviations, and acronyms used in this report.

2 2 The Framework of the Industry Study

This chapter introduces the research context of the industry study. It starts by a section, also summarized in Appendix B, defining the most central terms used in this report. This is followed by a short section presenting the research framework of semantic integrity. Finally, the chapter is concluded by a presentation of the research project Skutt and its focus on contracts, as a tool for striving towards semantic integrity in software products. The industry project itself and its characteristics are described in the next chapter.

2.1 Some Terms used in this Report

This section defines some central terms that are used in this report. Some terms related to modules, contracts and interfaces are defined, followed by some terms about errors. The term module will be used in this report for a well-delimited part of a software system. A module that is offering services to other modules is called a service supplier. It is described in a specification, sometimes called an API, and materialized by an implementation. The modules that are using its services are called its clients. The same term is also used for the client side in a client/server configuration, like a web browser being the client of a web server. When the term client is used in this report in the former meaning, both client and supplier are modules that are parts of the product. Used in the latter meaning, the client is a web or wap2 browser and the server is the product itself running on a web server. The context will make it clear which kind of client is intended in each case or the term client module will be used to stress the intended meaning. A person responsible for the design and programming of a module is called a designer. The designer for a client module is called a client designer. A supplier offers its services through a set of operations, implemented by methods. The semantics of a system, a module, or an operation refers to its interpretation or meaning, as opposed to the syntax, which refers to the rules governing the textual composition. Operations are specified by interface descriptions, having a syntactic and a semantic part. The syntactic part is specifying the name, the arguments, and possibly a return type for each operation. This is frequently called the signature of the operation, as for instance in C++. The semantic part of the interface description is describing the task performed by the module. The semantics of the module operations may be described through contracts, defining the responsibilities for both the operations and its clients. A contract consists of a precondition and a postcondition. The precondition specifies what the client module should satisfy before the call, and the postcondition specifies what a method implementing the operation should achieve, provided the precondition was satisfied initially. A strong contract places specific requirements on the client in order for the supplier to produce a particular result. A weak contract has few or no preconditions, defining a result in all circumstances. There is some confusion regarding the use of the term interface. Its real meaning is “a boundary across which two systems communicate” 5. In the context of establishing a communication between a client module and a supplier module, this boundary has both syntactic and semantic aspects. The most common usage of the term interface, however, only

2 Wap is similar to the wide world web, using the markup language WML instead of HTML. The browser runs on a cellular telephone and both the corresponding WML pages and the wap protocol itself are adapted to the special characteristics of cellular telephones. 3 includes the syntactic description. This is exemplified by COM, CORBA, and Java, where an interface definition is the specification of the syntactic details for the operations. In this report, the term signature will be when this limited sense is intended, and the term interface will be used for the broader sense, covering both syntactic and semantic aspects. A designer may produce a wrong specification, misunderstand a specification, or for some other reason produce an incorrect design or implementation. He then commits an error. An error may result in a fault being introduced in the product, so that for instance the resulting documentation or software is incorrect. When executed, a faulty program may fail to present the correct behavior. This is a failure. These definitions of error, fault and failure conform to 2. The purpose of testing is to detect faults in the product by provoking failures. At EIN, such failures are reported in trouble reports, a term that will be used also in this report.

2.2 The research context of semantic integrity

The term integrity is defined by the IEEE as “the degree to which a system or component prevents unauthorized access to, or modification of, computer programs or data” 4. The Swedish National Encyclopædia (Nationalencyklopedin) defines integrity as "knowing one's goal and being able to act according to one's conviction and resist to pressure"3. Another definition of integrity is “being true to a purpose or design” 6. Transferred to the area of software modules, to maintain the semantic integrity of a module means that its design should remain faithful to its purpose and resist to pressure. More specifically, both the implementation and the use of all the operations of the module should be in agreement with the intent of its operations as declared in the interface specification. A system can maintain its semantic integrity if none of its components is threatening the semantic integrity of any of the others so that they work well together to accomplish the purpose of the system. Systems that do not have sufficient integrity will break down after a period of time (paraphrased after 6).

2.3 A Presentation of the Research Project Skutt

The full name of the research project is “Improved software quality through semantic descriptions”, in everyday work called Skutt4. Skutt is carried out by the software engineering research group at Karlstad University. The research context for this group is semantic integrity and the current focus area is design contracts. This concept is explained in the first subsection, followed by a subsection discussing some different views on the term interface.

2.3.1 The focus area for Skutt: Semantic descriptions through design contracts Skutt promotes semantic integrity by making well-known principles for semantic specifications available to software developers in a pragmatic way. The principal conceptual tool for this is design contracts. The expectation is that a pragmatic application of design contracts will make it easier for software developers to increase the quality and integrity of their products. This research targets software engineering departments producing non-trivial systems, but where the system requirements do not justify the investment in and application of a formal specification and correctness proving technology. When developing large and complex systems, different people or teams of people develop different parts of the system. A system part may for instance be one or some modules. When

3 integritet (lat. inte’gritas, av i’nteger 'orörd', 'hel', 'fullständig', 'oförvitlig', 'hederlig'), helgjutenhet, vilket innebär att veta sitt mål och kunna handla efter sin övertygelse och stå emot påtryckningar. 4 Skutt is an extended acronym in Swedish coming from “Semantisk kvalitetsutveckling”, which may be translated to “Quality development through semantics”. Skutt also means a leap.

4 these parts are put together, it is crucial that the interface between a module and the rest of the world is well defined. The book "The Unified Software Development Process" written by “The Three Amigos”5 describes the recommended development process to be used with UML. It expresses this composition principle in the following terms6.

One individual is responsible for a service subsystem within a design subsystem. A group is responsible for a design subsystem. If the individuals or small groups are to work with a reasonable degree of independence, the interfaces that bound their areas of activity must be solid. To emphasize the importance of these interface specifications, they are sometimes called contracts. A contract commits the current developers and those in subsequent cycles to this interface. It is the fact that an interface is firmly established that makes pluggable architecture possible. Later, developers can substitute another subsystem, as long as they do not break the interface contracts.1

This quotation uses the term “interface contract”, presumably implying the contractual, that is the semantic, part of the interface. However, the term is not well defined and this meaning is covered by the term contract in this report.

2.3.2 Different views on interfaces When it comes to practice, as mentioned above, the predominant way to specify an interface is to specify the signature of the operations. The semantics is frequently described through intuitive and self-explanatory names for operations and their arguments. Sometimes an informal, more or less structured description of the operation and its input and output conditions is also given. The contract ideas, translated into a structured and disciplined use of preconditions and postconditions, do not seem to be in common use 7. Violations to the syntactic integrity of modules and operations can be detected automatically by compilers, but automatic support to maintain the semantic integrity of a module is limited. At best, one may manually read and interpret the names of the operations and their parameters and informal descriptions. Formal methods exist to follow up the semantics in a structured way in order to avoid misunderstandings, but such methods are generally conceived as being difficult both to learn and to apply. They are not widely used in the target group for Skutt. The objective of Skutt is to contribute to filling the semantic gap between intuitive descriptions and formal specifications. A method to introduce contracts in a pragmatic way in software engineering should be developed during the project. This method should improve the semantic descriptions and reduce the errors related to misunderstandings between the developers of different modules.

5 Ivar Jacobson, Grady Booch and James Rumbaugh 6 In this quotation, the system parts are called “subsystems”. 5 3 The Object of Study

The department of computer science has established a cooperation with EIN, one of many software development companies within Ericsson Sweden. EIN supports Skutt by giving access to projects and historical data and by participating in the development and application of the method. The industry study took place in a project run at EIN during the spring 1999. This chapter describes the industry project studied, as well as the product developed during the project. Some objectives and characteristics that are relevant for this study are described, for the product as well as for the project. This also includes some notes that are needed as background information on how the work in the project was organized.

3.1 Objectives and Functionality of the Product

The project emerged after a request from a customer, which was a telecom carrier, to deliver the framework for a flexible, user configurable wap service. It was initiated at the wap section at division EIN/L and was carried out during the spring of 1999. The objective of the project was to develop the product, a general support package to be fitted into a larger system developed by other Ericsson companies. The actors involved in using, buying and producing the product are shown schematically in Figure 3.1.

subscriber User uses the product through

subscribes to services from

<> Telecom Carrier Browser customer client calls across Internet manages buys the product from

server Product produces

Ericsson

Figure 3.1-The principal actors for the product and their relationships

The product should allow a telecom carrier to offer basic wap based services to its subscribers, who would be the end users of the product. The product should be accessed across Internet via the wap protocol from the wap browser of wap enabled cell telephones, but

6 also optionally from standard web browsers. It should give the subscriber flexible access to information from his wap or web browser. The information could for instance relate to carrier services subscribed to or it could be links to interesting information or services on the Internet. The information should be organized in hierarchical menu structures available in the browser to capture different parts of a user's needs. The selection of a menu item would for instance call a service from the carrier, load a page from an Internet site or select a new menu. The product should let each individual user use a standard browser to organize his or her information and menu structure in the way best suited for the personal needs. The actual menus should be stored on the carrier’s server and presented to the user as dynamically created wap or web pages. The services offered by the product should include browsing the user’s personal pages well as the services and Internet bookmarks he chooses to include in his menus. The actual telecom services available to a user would be defined by the subscription conditions. It had been decided that the product should run on a web server and that the software part of the product should be developed using the Java Server Pages (JSP) technology, made for creating dynamic HTML and WML pages. Included in the specifications was also a requirement that the access to the basic services offered by the product should be open so that the carrier could easily add their own services.

3.2 Characteristics of the Product

The product was specified to have a simple architecture. It should act as the server in a client/server system, as shown in Figure 3.1. The clients would be wap browsers, located in cellular telephones, or standard web browsers. They did not call for any development. What needed to be developed was the set of web or wap pages to be accessed by the browser. They should be dynamically created by the server side software, to be developed by the project. It had been decided that the server software should have a 3-tier architecture consisting of a user interface tier, a business logic tier and a database tier, as illustrated by the three boxes in Figure 3.2. The two uppermost tiers, contained within the thin line box, were produced by the project. The lowermost tier reused existing technology. The Man-Machine Interface (MMI) of the user interface tier would consist of diagrams with sequences and contents of dynamic wap or web pages. The semantics implicitly defined by these MMI diagrams would be implemented by the Graphical User Interface (GUI). The wap user interface would be text based and the web user interface would be based on the graphical web browser pages. The user interface part of the system consisted of three modules, for the creation of user wap pages, user web pages and system management web pages respectively. In this report, this subdivision is not important, and this tier will be called indifferently the GUI tier, the GUI module, or the GUI software. The business logic tier would manage the business logic. This should include the management of the data structure behind the user menus and the information database structures. It should supply a well-defined interface to the GUI tier to efficiently build the dynamic wap or web pages. The customer of the system wanted to be able to continue to develop their own user services on top of the business logic tier, so the interface to that tier should be open and well defined. This tier was going to consist of two modules, a business logic interface module and a database interface module. These modules will be called the BLI module and the DBI module respectively in this report. The product was going to be based on an existing, general-purpose database. For two different reasons, however, there was a need for a DBI module that should encapsulate the database access. On the one hand, the DBI module should incorporate some knowledge about

7 the storage structure specific to the product. On the other hand, it should isolate the product from the specific database technology. The DBI module defined a limited number of general- purpose application-related operations, some of which were non-trivial to understand and call correctly. The BLI module translated these operations to a large number of special purpose operations that were easy to understand and call, corresponding to the needs of the GUI designer team. All the DBI operations and most of the BLI operations were defined using strong contracts. The third tier was responsible for the physical access to the underlying database. In the project, the database was a distributed, high performance, high fidelity LDAP database and the access to it was through a ready-made Java bean, called DB in this report. This is indicated as the DB module in Figure 3.2.

Man-Machine Interface (MMI) design only

Graphical User Interface wap module web module GUI module (GUI tier) mgt module Interface required by the customer Business logic interface (BLI) module Interface required Business logic by the project (business logic tier) Database interface (DBI) module

Underlying database access and storage technology DB module (DB tier )

Figure 3.2-The architecture and the principal modules of the product

3.3 Characteristics of the Project

This section describes some characteristics of the industry project studied. The description may be used as a reference for comparison to other projects, to see if the lessons learned here are likely to apply to the other project. People we have talked with expect this type of project to be increasingly common in the future. The project was of a relatively small size, with about 10 participants. The time between project start and delivery was relatively short, about six months, and the pace of the development work was high. The life length of the product was expected to be limited to around two years, due to the fast development in the area of wap products and technology. The product was the second generation of its kind developed by the same section at EIN. The first generation was produced using CGI and Perl scripts for the dynamic server pages. The development team was almost the same and the product specifications similar, with the exception that this product should have more advanced functionality. In this new version, the user should for instance be able to store bookmarks to frequently visited Internet sites. Nearly

8 all the team members already knew the kind of product to produce and the product architecture and project organization from the previous project were reused. One important property of the project was that it involved many different technologies and tools. Some tools were newly developed, some were poorly tested, and some were new to the project members. One example of the last kind was the development language. JSP is based on the Java programming language and the project leader and the researcher were the only project members who had any practical experience with Java prior to the project. The environments for Java development and JSP runtime were other new factors that nobody had been working with before. The subscription manager server that kept track of the system subscribers and their subscription options, and the pre-made Java interface to the LDAP server were other new areas.

3.4 Organization of the Project

This section presents three characteristics of the project organization that may have semantic implications. The first is the mode of management chosen, where some management responsibility was delegated to most of the project members, and many running decisions were taken collectively in the development lab. The second characteristic is the organization of the design and development work, which varied for different modules of the product. The third characteristic is the simplification of the process model for the project, which was motivated by the small size of the project, the qualifications of the designers and the strong internal synchronization.

3.4.1 Delegated and synchronized project management Most members in the project team had some project management responsibility assigned to him or her, in addition to the primary task as designer. Some of the roles assigned were project manager, design manager, MMI manager, technical manager, configuration manager, and test manager. This delegation had the positive effect of distributing responsibilities and attributing importance to each team member. The project organization was quite informal with few formal meetings. The project manager and design manager worked very tightly together as a leader team. During the most intensive production period, most of the team members were working in a common lab with continuous informal contact. Upcoming questions were solved, partly informally between the designers in the lab, partly during the daily and weekly project meetings. This provided a strong synchronization between the team members.

3.4.2 Organization of the work The development work itself was organized differently for different parts of the product. The contents and flow of the displays in the graphical user interface was planned by the MMI responsible. MMI structure charts were drawn and reviewed by the whole group and control flow maps were distributed to the designers involved in programming the dynamic GUI pages. The programming of the GUI pages was organized as a group activity with a low level of formalization. The designers worked closely together and discussed the various issues as they appeared. For the business logic tier, the responsibility for the design and development was delegated to two designers, the one responsible for the same tier in the previous project and the researcher. They were supported by the design manager and the rest of the team when needed. The business logic tier was divided in two modules, as presented earlier, the upper BLI module and the lower DBI module. The task of the BLI module was to supply the GUI modules with the necessary business-logic functionality. This functionality was built around a

9 general structure and successively refined and complemented as the need for new operations arose from the GUI team. At the end of the project, the BLI module presented a large number of specialized operations that were straightforward to use. The DBI module, on the other hand, was presenting a small amount of business specific add-ons to the basic database operations for searching and modifying information in the database. It was designed and implemented as a separate task early during the project, since it was needed by the rest of the project team to build on.

3.4.3 Simplified process model As the project was not particularly large, the project management had decided to reduce the administrative process management overhead to keep it from getting out of proportions related to the project as a whole. Apart from the small project size, two characteristics of the project supported this decision: the qualifications of the designers and the strong internal synchronization. The project was small and based on qualified individuals. Every designer took responsibility for his part and would ask for help at his own discretion. At the same time, the project was strongly synchronized. Unclear issues were solved by informal discussions in the common development lab and during the daily and weekly coordination meetings. The simplifications had the implication that some documentation was left out and that some formalities regarding inspections and milestones were alleviated. The pace of the development was high and it was believed that for instance inspections would have slowed the project, without giving any obvious added value. The idea was that the continuous exchange of information, made possible by the small team size, as well as running informal communication with the project management should compensate for these simplifications.

10 4 Observations and Consequences

This chapter describes some observations made during the project, with relevance for the objective of the study, and their consequences. This implies that only those observations that have a bearing on semantic issues are reported. The observations are structured according to the three areas of interest announced in Chapter 1, the planning and management, the work and the product. The next chapter analyzes the observations and draws some lessons from them.

4.1 Planning and Management

This section has two parts. The first part describes the distribution of the design responsibilities and the effect of a temporary lack of design manager. The second part describes how the work in the project was organized.

4.1.1 The design responsibilities There were three areas of design in the project, system design, MMI design and module design. System design included incorporating user requirements, defining the system architecture, setting overall strategies and coordinating the parts of the product. It was assigned to a designer assuming the design manager role. MMI design included the elaboration, design and linking of the user dialogs corresponding to the use cases for the product. MMI design was assigned to a MMI manager. Module design included the detailed description and implementation of the modules of the product. The responsibility for this was distributed to the individual designer, within the frames set by the system design and the MMI design. The design manager would be the arbiter in case of uncertainties or conflicts. From the start of the project, the design manager was allocated to the project at 40%. As the project went on, his focus shifted gradually to tasks in other projects and his engagement in the project decreased. This successively created a vacuum regarding the responsibility and coordination for all kinds of design decisions that continuously needed to be taken. About two thirds through the project, he was replaced by a new design manager. According to the project manager, the period without a design manager was about two weeks. However, this happened during a busy time in the project, so for the designers working in the project, the lack of a readily available design manager was noticeable. The first design manager gradually reduced his engagement, which affected the project even before he formally left it, and the new design manager needed some time to take on his new responsibilities. Both of these facts probably contributed to this feeling. This lack of design manager was in conflict with the planned strategy mentioned in Section 3.4.3, stating that many design decisions should be taken along the road, as the need appeared. That strategy would require continuous design coordination. During the time gap, nobody had the overall view of the system and it was unclear who was responsible for the decisions. Sometimes, decisions had to be changed when new information was known. During this period, the project suffered from the lack of continuity in both functional and semantic decisions.

11 4.1.2 The organization of the work The responsibility of MMI manager involved two aspects. One aspect was the design of the contents and layout of the user interface displays and the other one was the design of the flow of control between these displays. The whole designer team reviewed this design, securing its quality and at the same time establishing a thorough understanding of the MMI among the rest of the designers. The design of the modules of the GUI and business logic tiers was delegated to the designer team. Time was not explicitly reserved for semantic planning, so the designers had to rely on their own initiative. Most of the team would work on the GUI tier, the requirements of which would be implicitly defined through the MMI design. The design and implementation of the business logic tier was assigned to two designers with the instruction that the design should be object-oriented, a difference as compared to the previous, similar project. On the other hand, similarly to that project, the requirements on the business logic tier would be defined successively as the needs appeared from the team developing the GUI tier. Especially the BLI module, which should interface the business tier to the GUI tier, would be developed in a relatively intuitive and iterative way with informal coordination. The monitoring of the progress had a strong focus on the implementation of the GUI operations, which involved most of the designers. The main metric was the number of MMI displays left to implement. The progress was reported and the staffing adjusted on a daily or weekly basis. This management was efficient and gave ample occasions for clearing upcoming semantic questions about the MMI. The business logic tier was monitored very informally. The task had been delegated to two trusted designers, and no problems were anticipated. No metric was defined and no explicit reporting was required, neither for its design nor for its implementation. One effect of this was that, differently from the MMI design, there was no common discussion of its functionality, which might have been useful from a semantic and structural point of view. Such discussions were intended to take place informally between the designers in the lab. That also happened, but the level of abstraction in that forum was too low for many issues. Another effect of the informal monitoring was that some delays in the implementation of the business logic tier passed undetected, which risked to jeopardize the time planning of the whole project. This contributed to an increased rush at the end, with an accompanying decrease in the attention paid to semantic considerations.

4.2 The Project Work

The observations made of the actual work show that the preplanned strategy was in general successful, but that the communication between team members was insufficient in some respects. This section reports the positive effect of a thorough design before implementation for the MMI and the BDI module, although, for DBI, this implied some impatience among the GUI designers. The iterative interactions between the GUI and BLI modules also worked fine. Insufficient communication caused problems in three areas, a newcomer developed the wrong semantics, the GUI designers misunderstood the semantic model of the BLI module and one designer implemented different semantics than the others.

4.2.1 Thorough MMI definition The MMI design for both the text based screen layouts for the wap phones and the graphical user interface for the web clients were planned together, as access by both wap and web should be equally allowed. It resulted on the one hand in a set of display layouts, and on the other hand in a control flowchart showing how the displays were linked together. These design elements determined the usability of the product as well as the semantics to implement

12 for the GUI module. The design work was carried out very thoroughly and the design was inspected by the whole group and refined in several iterations before they were distributed to the GUI designers for implementation. The operations implemented in the GUI module were not complicated, and it seemed that the intuitive semantic description offered by the displays and flow charts from the MMI were enough. This offered a somewhat coarse description of the functionality. The last details about the presentation and functionality were solved collectively as described above. The development of the GUI module was very efficient. As far as we could observe, this was mainly thanks to the thorough preparation of the MMI in combination with the printed displays and control flowcharts distributed to all the designers.

4.2.2 Design before implementation of DBI The design of the DBI module had a high focus on semantics. Due to some startup delays, the module had a very tight time schedule, since it was needed by the GUI team. The module first went through a strict design and definition phase, where the data structures and the semantics in the form of contracts and implementation invariants were defined. This of course took time and created some impatience among the GUI designers.

4.2.3 Focus on contracts in DBI The implementation of the DBI module strictly followed the defined contracts, assuming rigidly that all preconditions would be satisfied by the client modules at all times. The implementation had a focus on implementing the contracts correctly and paid no attention to possible error conditions resulting from violations of the contracts. This approach allowed the implementation phase to be short. It was also amply rewarded in terms of reported faults. Only at a couple of occasions after delivery to the GUI team, it was necessary to go back and correct or modify any code or definition in this module. In summary, the strategy of a thorough design followed by a focused implementation proved successful.

4.2.4 Iterative development of BLI Section 4.1.1 describes the iterative work model for the modules. The design and implementation of the API for the business logic tier was largely done in parallel with the development of the GUI modules. Once the basic structure for the business tier was established, this was a successful strategy as long as there was active design coordination.

4.2.5 Lack of communication A lack of communication with a designer who was new to the team caused some misunderstandings. This led to the effect that the initial design for the business logic tier did not correspond to what was needed by the GUI module. In the previous, similar project, the business logic tier was made as a single module, integrating both the database organization and the functional support for the GUI tier. In the present project, the new designer was asked to make an object-oriented business logic tier to support the GUI team. However, he did not realize what kind of interface was expected and how that interface was going to be used. Consequently, he designed a general-purpose interface that gave good application-oriented data support but was too complicated to use for the GUI designers. As will be explained in Section 4.3, the GUI designers needed the support from an API with specialized operations that were easy to understand and use correctly. The problem was discovered by the team and settled by the design manager. He decided that the defined module should be the DBI module and that a new module, the BLI module, should be constructed between it and the GUI tier. However, time was lost, so the design of the BLI module was not as good as it should have been. Nevertheless, it worked fine.

13 4.2.6 Initial lack of respect for strong contracts The BLI was designed with strong contracts7, assuming rigidly that the operations are only called in meaningful situations. For example, an operation to get the name of a display element had the precondition that the element actually existed in the display. No result was specified if it was not. The GUI designers, who were the client designers, were told that the API used strong contracts, implying that they had to establish the precondition before calling any of the operations. The API was documented using javadoc and made available online for the GUI designers. According to the theory of design by contract 3, the outcome of an operation when its precondition is not satisfied is explicitly left unspecified. This allows the implementation to handle such a situation any way it finds appropriate. This includes the freedom to let the system crash. This opportunity was exploited for the BLI operation. During the first period of the project, there were many system crashes, which created a lot of frustration among the GUI designers. After a while, however, they learned to respect the requirements imposed on them by the strong contracts. Actually, they had no choice if they wanted their software to survive the calls so that they could proceed with their work.

4.2.7 Insufficiency of informal communication It was assumed that all the designers were familiar with the system that they should construct from the previous similar project. Consequently, each GUI designer was assigned a part of the GUI to implement and upcoming questions were discussed and solved in common. Nevertheless, late in the project it was discovered that one of the designers apparently had not taken advantage of this common discussion forum. He had implemented the GUI operations in a different way than all the others. Parts of his work had to be redone and the project was delayed.

4.3 The Resulting Product

This section describes some semantic properties for the different parts of the finished product followed by some special considerations for the client/server interface. Finally, some observations about the distribution of faults in the product are reported.

4.3.1 The Database Interface module (DBI) The DBI module defines a product-related data manipulation on top of the general-purpose database storage tier. It consists of two product-related class hierarchies with in all 16 classes, each hierarchy defining 20 public operations. The API for the DBI module uses strong contracts for all the operations. This is a natural consequence of the usage pattern of the module. If for instance an end user wants to remove an element from his menu structure, he will point at that element in an editing menu and click on the Remove button. Therefore, the strong precondition, requiring that the display element actually exist, will automatically be satisfied. Applying strong contracts did not impose any extra overhead when the higher level modules were developed, but highly simplified the implementation of the DBI module. The DBI module defines basic operations to retrieve, add, remove, and manipulate product data in a structured way. The operations are atomic and highly reusable, but require a high level of understanding and focus to be used correctly.

7 Meyer 4 refers to this as the demanding approach to contract design or the “tough love” approach.

14 4.3.2 The Business Logic Interface module (BLI) The requirement for using the DBI operations was satisfied by the development team for the BLI module, which only consisted of the same two persons who designed the DBI module. However, it was not satisfied by the development team for the GUI module, which consisted of half a dozen designers working at a high pace. A database operation is rarely used on its own, but operations are composed into call sequences of varying length and complexity. To require that the GUI designers should assemble their own solution every time they needed a database access would have complicated their task and would inevitably have led to lots of errors. What they needed was a business logic tier that offered a simple way to have things done. They needed specialized, easy to use operations oriented towards the user’s needs. Ideally, one operational need for the GUI software should be expressed as one single operation in the BLI. The BLI module gives this support to the GUI software. The BLI module transforms the specialized needs of the GUI software to the more general but more complicated operations offered by the DBI module and trivializes the GUI development work. The BLI module has a simple, functional interface. Similar but not exactly identical operations translate into different BLI operations, so the BLI operations are highly specialized, and each operation has a low degree of reusability. The BLI tier consists of one class with more than 54 specialized, public operations. The implementation of one operation ranges from a call to one single DBI operation to complicated sequences of operations. The implementation of the BLI operations themselves is relatively straightforward. The strong contracts defined in the DBI tier are propagated to the user interface tier. The business logic operations are defined with strong preconditions. These preconditions are satisfied in a natural way when the system is used.

4.3.3 The user interface tier The GUI tier is the implementation of the MMI design, which consists of a large number of user displays. The same MMI is implemented twice. One implementation set is WML based and aimed at text-based wap telephones, the other one is HTML based and aimed at graphical web browsers. For the most part, the GUI programs are not complicated, but characterized by a large number of similarly constructed user displays. The differences lay in some layout details. These include a small variation in the components of the displays, the names on command buttons as well as other display elements and, of course, in the differences in the results of the commands. These differences were limited but still had to be tailored to each individual display. They are reflected in small variations in the programs constructing the displays. The most striking characteristic of the GUI module was the large amount of user displays that had to be programmed. It resembled a mass production situation, with the difference that each individual display had to be programmed individually since not two of them were exactly equal. The operations implemented in the GUI module were not complicated. However, there were many designers involved in the production of the GUI module and there were many operations to implement. For this mass production to work, it was important that the operational support offered to the GUI was simple and tailored to the specific needs. This support was supplied by the BLI module.

4.3.4 Design considerations for the open client/server interface As mentioned in Section 4.3.2, strong contracts were used by the business logic tier. Since the interface between the GUI tier and the business logic tier is an internal interface, it is natural to use strong contracts there. Furthermore, the way the user interface tier would use the operations in the business logic tier would automatically satisfy these preconditions.

15 In the context of the product, the user would be located at the client site and the product at the server site. The client program could be an ordinary web browser and the user displays would be dynamically created web pages. The mechanism for calling server operations from the client computer is through URL strings with embedded parameters. These strings are captured by the GUI tier at the server site and transformed to calls and parameters to operations in the business logic tier. The commands from the client software to the server are activated through buttons and other graphical widgets in the user interface, which in turn is under the control of the GUI tier at the server side. However, these commands may be intercepted and controlled by the user at the client browser. The user may for instance replace the command generated by the browser by a typed URL command string, which may contain errors. Such strings may also be saves as bookmarks, which make it possible to repeat a command at a later point in time, where it may be invalid. The same effect is obtained by the "Back" button of the browser, which resets the user interface to a previously displayed page. The operation on that page, which may now be illegal, will then be redone. If, as an example, a web page lists some user elements and the user chooses to delete one of them, that element will be deleted. If he then uses the Back button, he may come back to the old, but now invalid, list of elements and choose to delete the same element once more. That command will then cause a system crash, since its precondition, that the chosen element is present in the system, is no longer satisfied. This is obviously not satisfactory. This open interface between the client and the server has to be taken into account when designing the semantic requirements that the business logic tier imposes on the GUI tier. One option is to have the GUI software check the preconditions before calling the operations in the business logic tier. Another option is to define weaker or more forgiving contracts that tolerate and handle certain errors that may be caused by erroneous user behavior. This issue was not dealt with consciously until quite late in the project. It was then judged impractical to add operations in the GUI tier to check the preconditions before calling the business logic operations. Instead, the initial strong contracts were changed into weak ones. The reason for this decision was partly that there were no operations in the business logic and the database tiers to support the necessary inquiries, partly that it was not desirable to introduce them at that stage. The solution was to weaken the contracts and let the underlying operations throw an exception in the situations corresponding to the normal precondition being violated.

4.3.5 Testing The number of problems found during testing and their locations give information on the quality of the product. Most of the testing of the product was completed before the writing of this report. In all, 102 trouble reports were written during testing. However, at the time of the writing of this report, the trouble reports are not studied in detail. The observations reported here are therefore not based on exact statistics but rather on general impressions. A significant part of the trouble reports, about one third, was related to details in the user interface. This includes messages and button functionality that did not follow the specifications. Another group of about 15-20% was related to missing or unclear specifications. In such cases, according to the test manager, the tester sometimes had his own opinions on how the system should behave, diverging from the MMI design. A trouble report could for instance say that a button should have the text “OK”, while it had some other text. This indicated that some more effort could have been put into completing the specifications ahead of the implementation of the individual displays. Surprisingly enough, some of the trouble reports relate to the linking of GUI displays, although that was clearly indicated in the MMI design. These faults may be the result of

16 specification modifications during the project that have not been fully considered in the implementation, an assumption that needs to be confirmed by further research. Most of the time, these faults were trivial and easy to correct. To the authors’ knowledge, only two trouble reports are related to faults in the DBI or BLI modules. One was related to a misunderstanding of the functional requirements and both were easily corrected. The transformations in the BLI module in order to weaken the contracts are not known to have caused any trouble reports.

17 5 Lessons Learned

This chapter highlights some lessons that can be learned from the observations reported in Chapter 4. The lessons are studied from a semantic point of view, which means that many important and interesting aspects are deliberately left out of the study. This study relates to one development project only, and therefore the lessons learned cannot automatically be generalized to other contexts. The lessons are structured according to the three areas of interest, planning and management, the work and the product, announced in Chapter 1. The first section reports the lessons related to the planning and the management of the project. Specifically, it looks at how planning and management can affect the semantic quality of the product positively. The second section reports lessons related to how the work was carried out. The third section reports lessons related to the various parts of the product. A summary of all the lessons learned is found in Appendix A.

The two first lessons in the area of planning and management encourage planning of specifications and design details. One lesson acknowledges that the plans may evolve during the work, so a strategy is needed to cope with that. The remaining lessons set the focus on coordination and communication within the team.

5.1.1 Communicate with the customer A large part of the trouble reports was related to missing details in the product specification. To avoid different interpretations by different persons, such unspecified details should be solved with the customer before implementation. The decision should be made under the control of a requirements specification manager, so that it will agree with the solution expected by both the tester and the customer. The lesson learned is that a continuous communication with the customer is needed, in order so solve new issues that come up during the development of the product. This implies that resources for specification requirements should remain allocated even during the development of the bulk of the system.

5.1.2 Plan details to avoid errors A large part of the trouble reports was related to details that were not initially specified. One way or another, these details need to be settled during the project. To avoid divergences in the interpretation of these requirements, their specifications, like the specifications of the initial requirements, should be managed by the requirements manager. The lesson learned is that even residual specifications should be settled in an organized way ahead of their implementation. This implies that resources for design management should remain allocated even during the development of the bulk of the system.

5.1.3 Implement changes in the specification throughout the product Some requirements or design specifications inevitably change as the understanding of the product increases. After a filtering process, some of these changes will be incorporated into the product version under development. Some of the trouble reports in the project are related to modifications that were not implemented throughout the whole product, a fact that led to semantic inconsistencies in the product.

18 The lesson learned is that the development method should capture evolving specifications so that the changes can be implemented throughout the product.

5.1.4 Manage the design to avoid misunderstandings Semantic concerns continuously emerged during the project. The main strategy for the module interfaces was settled early, but ideas and questions keep coming up, both about the general guidelines and about specific issues. As an example, we saw how a design manager was needed to settle the misunderstanding concerning the business logic tier. The lesson learned is that it is important to have, during the whole development period, an active design manager who has the full overview, sets the priorities, and settles new questions that arise.

5.1.5 Inform newcomers One problem that delayed the project was that the researcher, as a new team member, was not sufficiently aware of the team's way of thinking. Most members of the team had participated in the previous, similar project and had a common understanding of how things were done there. The researcher did not share this common understanding with them. This was particularly clear during the design of the interface that should support the GUI tier. The researcher thought that he understood what the other team members meant when they discussed the functionality of the business logic tier. He also thought that his discussions with his partner during the development of this interface should guarantee that he had a correct understanding. In retrospect, we realize that his understanding should have been discussed with several of the other team members, so that the interface defined could have matched the expectations of the whole team. The lesson learned is that there should be an active consciousness about the issue of common understanding, to avoid a semantic mismatch between team members. Every team member, and newcomers in particular, should get a common understanding of the culture and expectations of the rest of the team. For example, the newcomer may discuss his assignment with several other team members, relevant areas may be discussed in common design meetings or some kind of inspection of his proposed solutions may be performed.

5.1.6 Plan for early detection of misunderstandings Section 3.3 describes the collective mode of work that was applied in order to solve problems that would come up during the development work. This proved to work to a certain extent. Upcoming issues were discussed and solved in common. However, only issues that the individual designer conceived as problems were solved this way. A designer may be on the wrong track without knowing it or he does not want to expose himself. In either case, he will not take advantage of the group to solve his problem. Such a situation arose in the project and was described in Section 4.2.7. Some additional mechanism for detecting misunderstandings or deviations from the common standard may be needed. One solution may be to use reviews or inspections. They are neutral and objective, focusing on the product and not on the person. At the same time, they are efficient for discovering both occasional and systematic misbehavior. For reasons of economy and time, many projects do not systematically perform inspections of all artifacts from the project. In that case, samples may be inspected in order to detect at least some systematic problems. In the simplified process for the project, described in Section 3.4.3, neither was done. Screening the artifacts from every designer should give at least two benefits, create a common culture and detect misunderstandings early, both of which are beneficial, especially when new technology is used as in the project. The lesson learned is that some mechanism should be implemented to detect misunderstandings early, for instance code inspections. Not all the code needs to be inspected

19 and the inspections do not need to be very formal. A screening where some code from all the designers is inspected or reviewed by some of the colleagues may be enough.

The first lesson about the project work acknowledges the value of a thoroughly planned design. The next four lessons are about using strong contracts, which were used in two modules. Two lessons summarize the advantages gained from using strong contracts, one is about the communication issue they highlight, and one clarifies that the transformation from a strong contract to a weak one is a safe transformation. The last lesson, of a more general nature, is that the designers should be aware of the fact that internal and external errors are of different nature.

5.2.1 Plan and document the MMI thoroughly The project has shown that programming with high productivity and few semantic errors is possible if the design is well planned beforehand. The MMI responsible had done a thorough preparation, with respect to both which user interface displays should be included, their contents and the linking structure between them. This made it possible to produce the software implementing the user interface at a high rate. The fact that half a dozen designers were involved in the production of this user-interface software enforces the positive effect of the planning. The semantics of the MMI functionality was described explicitly but informally through their contents and flow and this appears to have been sufficiently formal. This explicit specification led to few semantic errors in the implementation of the man-machine interface. The lesson learned is that a detailed planning with an explicit focus on semantics is profitable, especially when many designers are involved in the production of the solution.

5.2.2 Use strong contracts for increased client quality Strong contracts were used extensively in the DBI and BLI modules, and they worked well. A strong contract requires the client module to assure that the preconditions required to successfully complete a called operation are satisfied. If not, the supplier makes no promise about the outcome of the call, which may return with a wrong result or not return at all. This grants the supplier a freedom in the handling of illegal situations. This freedom was exploited in the business logic tier to let the program crash through uncaught illegal pointer exceptions or index out of bounds exceptions, forcing the client designer to correct the mistake before his program was allowed to proceed. This had the advantage that the client designers were made aware of illegal calls and could correct them early. This in turn translated into very few functional faults in the GUI tier. The lesson learned is that, in situations where they apply, strong contracts serve to detect and remove client module faults very early, thus contributing to a free fault-free product.

5.2.3 Use strong contracts for increased supplier quality The strong contracts used in the business logic tier made it possible to design and implement that part without too much delay. The work could be focused on producing correct code and not on handling illegal situations, thus saving implementation time. They also made the supplier module simpler, which in turn contributed to a fast production, few faults, a short testing period and, hopefully, few incidents after delivery. It should be noted however that a thorough design was required to obtain these benefits, as noted in Section 4.2.24.2.7.

20 The lesson learned is that, in situations where they apply, strong contracts allow a fast development and high quality in the supplier module, thus contributing to a timely and fault- free product.

5.2.4 Actively inform client designers about supplier semantics Initially, the GUI designers used the BLI module with incorrect assumptions. This resulted in unnecessarily many system crashes during the first test runs. It appears that the strong contract model used in the BLI module was not sufficiently well marketed to the GUI designers. They did not seem to be aware of their role in these contracts and did not make sure that the preconditions were satisfied before calling the operations. The lesson learned it that the information transfer between groups of designers must be active. It is not enough to document the module description, for example using javadoc as in the project. Client designers of a module must both read and understand the semantics of the operations before they produce their client software.

5.2.5 Start out with strong contracts At a late stage, the specifications for some of the BLI module operations were redefined from strong to weak contracts. This did not cause any particular problem in the project. This corresponds well with the theory in the area, expressed for example by Barbara Liskov’s substitutability principle 8 and Bertrand Meyer’s open-closed principle 4. Changing a strong contract to a weak one is a substitutable change, which does not affect the clients negatively. A change the other way, from a weak contract to a strong one, is not substitutable and has a major effect on all client modules. The lesson learned is that it is safe to start out with a strong contract and then weaken it if necessary, through modification of the supplier module or through a wrapper module. The opposite is not true.

5.2.6 Differentiate between errors and errors This project has helped us to be aware of the difference between two kinds of errors, those made by the users of the product, and those made by its designers. Errors in the use of the product can never be eliminated and must be taken care of by the product. Design or programming errors, on the other hand, should be eliminated, so the product should assist in detecting them. Weak contracts are convenient for user interfaces to take care of user errors. This implies that there should be a strategy for handling of user errors and that this part of the product should contain code implementing this strategy. Strong contracts, on the other hand, have shown efficient for the early detection of faults introduced by the client designers of a module. The lesson learned is that a distinction should be made between external and internal errors and that the contract should be applied. External errors are performed by an actor outside of the system, and internal errors are performed by the designers and programmers of the system. The corresponding interfaces should be defined with weak and strong contracts respectively.

One lesson learned about the product itself is to match the complexity of a module and its usage pattern. This is like impedance matching of electrical circuits. The other lesson reported here is to distinguish between external and internal interfaces in a product, and that the HTML interface should be treated as an external interface.

21 5.3.1 Match the complexity of an API to its use As described in Section 4.3.2, there was a mismatch between the interface offered by the DBI module and the needs of the GUI designers. The database module was general and relatively complicated. It required each particular use case to be assembled by a sequence of operations. The GUI programmers, on the other hand, were expected to produce a high number of GUI routines at a high speed with a high degree of diversity. They required an interface where a use case could be easily implemented on top of one or a few straightforward operations. The BLI module, with structured, simple and intuitive semantic descriptions, solved that problem for them. The BLI module was made by only two designers and each specialized method was going to be produced only once. These two designers could afford to know the underlying database module well enough to correctly package the necessary specialized operations, which could then be supplied to the GUI tier as one operation. The lesson learned is that the semantic definition of an interface should match the expected use pattern. A simple interface should be defined when there are many client designers, high development speeds or application software of low complexity. A more demanding interface can be defined when the client module is expected to be complex and there are few client designers, who are willing to spend more effort on learning to use the interface correctly.

5.3.2 Handle client/server interfaces as an open user interface Normally, strong contracts may be used inside a software system and weak contracts on the system boundaries. This approach was used in the project, where strong contracts were applied in the business logic tier. As the project progressed, however, it stood clear that this solution was not satisfactory, due to the open interface between the web client and the server. This interface had to be managed in the same way as a user interface, since the user was able to influence it directly. Such interfaces need weak contracts, which do not assume a correct usage. The lesson to learn from this is that a distinction should be made between interfaces that the user can influence and interfaces that the user cannot influence. The interface between the web browser and the web server can be influence by the user and should be treated as an open user interface and specified with weak contracts.

22 6 Conclusions and Further Work

This section summarizes the observations and the lessons learned described in this report. The structure is the same as in the presentation of the observations and the lessons learned, starting with planning and management, continuing with the project work and ending with the product. Finally, the section sketches some areas that may deserve further study within the area covered by the report.

The fact that the system design was quite rough was not seen as a problem, as far as we could observe. Spending more time and giving more details on the system level would be to repeat what everybody already knew and would probably not have changed the work in the project. The thorough MMI planning allowed a fast and efficient implementation of the GUI tier. The semantics of each operation seemed to be described well enough through the implicit definition given by for instance flow diagrams and button names. There were two problems worth mentioning. One was that the changes, resulting from successively increased understanding, were not always reflected in the diagrams and the implementation, and this caused some extra trouble reports. The other problem was that many design details were not defined before their implementation. This caused some inconsistencies in the MMI model in addition to some trouble reports about unspecified features. The conclusions for the detailed module design of the BLI module and the DBI module different slightly. For the BLI module, a better understanding of, and more focus on, the initial design could have improved the structure of the module and its operations. However, the semantic aspects regarding how the operations were specified would probably not have been treated differently, with one exception. A more thorough initial analysis, the operations crossing the open client/server interface would have been designed with weaker contracts, as reported in the sections 4.3.4 and 5.3.2. Alternatively, test functions would have been added to match the preconditions for the strong contracts. For the DBI module, time was allocated for design and semantic definition as part of its construction. This resulted in an efficient and practically error-free implementation of this part.

The work in the project was organized as a collective, iterative development with weekly checkpoints. In general, this model worked well for this project. Three weaknesses were observed, though. One problem was that the system management role was discontinued during a period, and that caused some uncertainties in the decision-making during the iterations. Another observation was that the collective working model did not capture well the fact that one designer implemented a solution that was diverging from the rest of the project. Finally, the communication about the design was insufficient. The problem was observed both for introducing a new team member in the structure of the product and in communicating the consequences of using strong contracts for the BLI API to the GUI programmers. Interestingly, theoretical results regarding strong and weak contracts were confirmed. The BLI API supporting the client/server interface was initially defined with strong contracts.

23 Towards the end of the project, some of them were modified to weak contracts. This could be done without causing any problems in the already finished parts of the product.

The project has demonstrated the importance of harmonizing the complexity and ease of use of a module with its use pattern. A module that will be used by a large amount of other modules should have a simple, intuitive and specialized interface. A module that is going to be used by few other modules may have a more general, interface. The project has also demonstrated the need to distinguish between different kinds of interfaces. An open interface that can be accessed by an end user should be defined with weak contracts whereas a closed interface that is accessible only from within the system itself should use strong contracts. The client/server interface across the Internet is an open interface. Weak contracts should therefore be used for the client/server API.

6.4 Further Work

This report is based on informal information from the project. An analysis of the trouble reports from the project will show the distribution of the causes for the failures reported. It would be interesting to study the distribution between semantic and other causes. The semantic causes are for instance unclear or wrong specifications, both on the system level and on the module levels. Non-semantic causes are for instance programming errors and misinterpretation or negligence of specifications. Such a root cause analysis could find out where in the system the semantic failures occur and study their reasons. Another interesting study would be to analyze the trouble reports and compare them to those of the previous project. The two projects have a similar objective and both project and system structure, but also many differences. Some differences are the development environments, the runtime environment and the use of contracts in the business logic tier. It would be especially interesting to study the impact the use of contracts to specify the semantics of the business logic tier has had on the product quality. This product quality can for instance be measured through the trouble reports.

24 References

[1] Jacobson, I., Booch, G., Rumbaugh, J., The Unified Software Development Process, Addison-Wesley, 1998, pp. 379-380 [2] Fenton, N. E., Pfleeger, S. L., Software Metrics, A Rigorous & Practical Approach, second edition, PWS Publishing Company, 1997. [3] Meyer, B., Object Oriented Software Construction, Addison-Wesley, 1988 [4] Meyer, B., Object Oriented Software Construction, Second Edition, Addison-Wesley, 1997 [5] The Free On-line Dictionary of Computing, http://www.dict.org/ [6] PCS Education Systems, Inc, http://members.edventures.com/terms/I/integrity/ [7] Blom, M., Semantic Integrity in Programming Industry, Master's Dissertation, Computer Science, Karlstad University, 1997 [8] Liskov, B., Data Abstraction and Hierarchy. OOPSLA ’87, Addendum to the Proceedings, October 1987.

25 A Summary of Lessons Learned

This appendix summarizes the lessons learned from the project that are described in this report. The full discussion of these lessons is found in Chapter 5. The numbering corresponds to the section numbers in that chapter. The following lessons were learned from the project:

A.1 Planning and management

1 A continuous communication with the customer is needed, in order so solve new issues that come up during the development of the product. This implies that resources for specification requirements should remain allocated even during the development of the bulk of the system. 2 Even residual specifications should be settled in an organized way ahead of their implementation. This implies that resources for design management should remain allocated even during the development of the bulk of the system. 3 The development method should capture evolving specifications so that the changes can be implemented throughout the product. 4 It is important to have, during the whole development period, an active design manager who has the full overview, sets the priorities, and settles new questions that arise. 5 There should be an active consciousness about the issue of common understanding, to avoid a semantic mismatch between team members. Every team member, and newcomers in particular, should get a common understanding of the culture and expectations of the rest of the team. For example, the newcomer may discuss his assignment with several other team members, relevant areas may be discussed in common design meetings or some kind of inspection of his proposed solutions may be performed. 6 Some mechanism should be implemented to detect misunderstandings early, for instance code inspections. Not all the code needs to be inspected and the inspections do not need to be very formal. A screening where some code from all the designers is inspected or reviewed by some of the colleagues may be enough.

A.2 The Project Work

1 A detailed planning with an explicit focus on semantics is profitable, especially when many designers are involved in the production of the solution. 2 In situations where they apply, strong contracts serve to detect and remove client module faults very early, thus contributing to a free fault-free product. 3 In situations where they apply, strong contracts allow a fast development and high quality in the supplier module, thus contributing to a timely and fault-free product. 4 The information transfer between groups of designers must be active. It is not enough to document the module description, for example using javadoc as in the project. Client designers of a module must both read and understand the semantics of the operations before they produce their client software. 5 It is safe to start out with a strong contract and then weaken it if necessary, through modification of the supplier module or through a wrapper module. The opposite is not true.

26 6 A distinction should be made between external and internal errors and that the contract should be applied. External errors are performed by an actor outside of the system, and internal errors are performed by the designers and programmers of the system. The corresponding interfaces should be defined with weak and strong contracts respectively.

A.3 The Resulting Product

1 The semantic definition of an interface should match the expected use pattern. A simple interface should be defined when there are many client designers, high development speeds or application software of low complexity. A more demanding interface can be defined when the client module is expected to be complex and there are few client designers, who are willing to spend more effort on learning to use the interface correctly. 2 A distinction should be made between interfaces that the user can influence and interfaces that the user cannot influence. The interface between the web browser and the web server can be influence by the user and should be treated as an open user interface and specified with weak contracts.

27 B Terms and Abbreviations

API Application Programmer's Interface. CGI Common Gateway Interface, a standard for interfacing external applications with information servers, such as web servers. client (module) A software module that uses the operations of another module, called a supplier. client (system) In the context of client/server, a client is a software system using services from another software system, being the server. client designer The designer of a client module. contract The semantic part of the interface description of an operation. customer The telecom carrier ordering the product. designer A person responsible for the design and programming of a software module. EIN Ericsson Infotech AB, Karlstad. EIN/L The division of EIN where the project was run. error A dynamic property of a human, something incorrect done by someone, for instance a user or a designer. An error may result in a fault. failure A dynamic property of the product, the product producing the wrong result during execution. fault A static property of the product, a deviation from the correct implementation of the product. A fault is the result of an error and may cause a failure. GUI Graphical User Interface, the actual graphical screens with their contents and functionality. The web based displays are graphical and the wap based ones are text based. HTML HyperText Markup Language, the language used to describe Internet web pages. implementation The program instructions that materialize a specification. integrity The degree of resistance to unauthorized use. interface The boundary between a supplier operation or module and its clients. In the expression user interface, also used for the boundary between the product and its end users. Internet A worldwide network of computers. JSP Java Server Pages, the technology used to develop the server part of the product. JSP is developed by Sun. LDAP Light Directory Access Protocol, a database-access protocol. method 1: The description of a way of working. 2: The implementation of an operation. MMI Man-Machine Interface, defining the dialogs with the user. That includes the sequences of screen displays presented to the user and the information and controls contained in them. module A well delimited part of a system. Sometimes called a subsystem. NUTEK The Swedish National Board for Industrial Research and Development operation A service offered by a supplier. Perl Practical Extraction and Report Language, a server script language for creating dynamic web pages.

28 postcondition A specification of what a supplier operation should achieve, provided its precondition is satisfied before the call. precondition A specification of what a client module should assure before calling a supplier operation. server A software system serving another software system, called a client. semantics The interpretation or meaning of a software system or some of its parts. signature The syntactic part of an interface description. Skutt The research project where this industry study is a part. specification A description of the properties of a system, a module or an operation. strong contract A contract placing specific requirements on the calls from client modules in order to define a result. subsystem see module. supplier A software module that supplies services to other modules, called its clients. syntax The rules governing the textual composition of a software program. testing The process of provoking the failure of a product in order to detect faults. trouble report Failure report at EIN. URL Universal Resource Locator, the address of a resource on the Internet. user A person who uses the finished software system, same as end user. The users of the product were subscribers to the telecom carriers buying the product. wap Wireless Applications Protocol. weak contract A contract not placing specific requirements on the calls from client modules in order to define a result. The situations that may result in meaningful results must be recognized by the supplier operation A contract with few or no preconditions, defining a result even with erroneous input. web The Internet based world wide web. WML Wireless Markup Language, the language used to describe wap pages to be displayed on a wap enabled cellular telephone.