Writing documentation about software internals is rarely considered a rewarding activity. It is highly time-consuming and the resulting documentation is fragile when the software is continuously evolving in a multi-developer setting. Unfortunately, traditional programming environments poorly support the writing and maintenance of documentation. Consequences are severe as the lack of documentation on software structure negatively impacts the overall quality of the software product. We show that using a controlled natural language with a reasoner and a query engine is a viable technique for verifying the consistency and accuracy of documentation and source code. Using ACE, a state-of-the-art controlled natural language, we present positive results on the comprehensibility and the general feasibility of creating and verifying documentation. As a case study, we used automatic documentation verification to identify and fix severe flaws in the architecture of a non-trivial piece of software. Moreover, a user experiment shows that our language is faster and easier to learn and understand than other formal languages for software documentation.
The use of logic to describe and check software architecture has been explored in depth @cite_41 @cite_35 . In this context, a number of different tools have been implemented, Reflexion Models @cite_38 , ArchJava @cite_0 , Lattix Inc's dependency manager @cite_2 , and Intentional Views @cite_27 . However, in contrast to the approach presented here, the resulting formal models of the architecture cannot be read and queried in a natural way and, as far as we are aware of, they have not been used in practice to software. Users are supposed to learn how to read and write statements in some sort of formal logic. This could be a major hindrance for the broad adoption of such systems, especially if the model of the architecture has to be verified by non-computer-scientists.
@cite_35 @cite_38 @cite_41 @cite_0 @cite_27 @cite_2
114886242 2021672791 2133254848 1617811580 2169291221
Software engineers often use high-level models (for instance, box and arrow sketches) to reason and communicate about an existing software system. One problem with high-level models is that they are almost always inaccurate with respect to the system's source code. We have developed an approach that helps an engineer use a high-level model of the structure of an existing software system as a lens through which to see a model of that system's source code. In particular, an engineer de nes a high-level model and speci es how the model maps to the source. A tool then computes a software re exion model that shows where the engineer's high-level model agrees with and where it di ers from a model of the source. The paper provides a formal characterization of reexion models, discusses practical aspects of the approach, and relates experiences of applying the approach and tools to a number of di erent systems. The illustrative example used in the paper describes the application of re exion models to NetBSD, an implementation of Unix comprised of 250,000 lines of C code. In only a few hours, an engineer computed several re exion models that provided him with a useful, global overview of the structure of the NetBSD virtual memory subsystem. The approach has also been applied to aid in the understanding and experimental reengineering of the Microsoft Excel spreadsheet product. This research was funded in part by the NSF grant CCR-8858804 and a Canadian NSERC post-graduate scholarship. 0 Permission to make digital hard copies of all or part of this material without fee is granted provided that the copies are not made or distributed for pro t or commercial advantage, the ACM copyright server notice, the title of the publication and its date appear, and notice is given that copyright is by permission of the Association for Computing Machinery, Inc. (ACM). To copy otherwise, to republish, to post on servers or to redistribute to lists, requires prior speci c permission and or a fee. SIGSOFT '95 Washington, D.C., USA c 1995 ACM 0-89791-716-2 95 0010...$3.50 Software architecture describes the structure of a system, enabling more effective design, program understanding, and formal analysis. However, existing approaches decouple implementation code from architecture, allowing inconsistencies, causing confusion, violating architectural properties, and inhibiting software evolution. ArchJava is an extension to Java that seamlessly unifies software architecture with implementation, ensuring that the implementation conforms to architectural constraints. A case study applying ArchJava to a circuit-design application suggests that ArchJava can express architectural structure effectively within an implementation, and that it can aid in program understanding and software evolution. Intensional views and relations have been proposed as a way of actively documenting high-level structural regularities in the source code of a software system. By checking conformance of these intensional views and relations against the source code, they supposedly facilitate a variety of software maintenance and evolution tasks. In this paper, by performing a case study on three different versions of the SmallWiki application, we critically analyze in how far the model of intensional views and its current generation of tools provide support for co-evolving high-level design and source code of a software system. An approach to managing the architecture of large software systems is presented. Dependencies are extracted from the code by a conventional static analysis, and shown in a tabular form known as the 'Dependency Structure Matrix' (DSM). A variety of algorithms are available to help organize the matrix in a form that reflects the architecture and highlights patterns and problematic dependencies. A hierarchical structure obtained in part by such algorithms, and in part by input from the user, then becomes the basis for 'design rules' that capture the architect's intent about which dependencies are acceptable. The design rules are applied repeatedly as the system evolves, to identify violations, and keep the code and its architecture in conformance with one another. The analysis has been implemented in a tool called LDM which has been applied in several commercial projects; in this paper, a case study application to Haystack, an information retrieval system, is described.