Rule Based Software Documentation – Documenting The Collaboration Aspect Of Software Systems

Structuring big software systems into reusable building blocks has proven to be an adequate mean to accomplish the increasing complexity prevailing in todays software projects. In such a scenario no object is an island and relations between participants of these mini architectures are crucial to understand the buildup of the whole system. However, the collaboration aspect of a software system cannot be adequately documented using inline comments as part of the source code. This is mainly because the scope of such a comment is limited to one following program construct, the di erent collaboration contexts of the observed program construct are yet disregarded and references to participants can be only provided literally in an informal manner. This thesis contributes a concept of a novel documentation approach that allows to adequately document object collaborations in software systems. A key issue is the separation of covered source code and related comments into di erent documents. A formal description of the collaboration is then needed to glue both concepts together and applies an MtoN relationship between programming code and comments. When browsing source code in an editor, documentation entries fade in context sensitive. In case of multi ple matching documentation entries, we will elaborate a set of heuristics to rank resulting entries by their relevance. Furthermore, an Eclipse plugin utilizing the concepts of this work will be implemented to demonstrate the usage of this new form of an internal software documentation. As a proof of concept, the tool has been tested in a case study covering three di erent sized software projects with documentation concerning their collaboration aspects. [...]
Rulebased Documentation 1 INTRODUCTION 1 Introduction Within the last decades, software projects have grown up remarkable. To actually accomplish the resulting complexity, humans usually try to raise the level of abstraction. So programming languages evolved from being strictly imperative to higher level languages. A well established result of this trend is object oriented programming, as becoming popular by the language Smalltalk in 1980. Object oriented programming allows the developer to abstract things from the problem domain to corresponding software objects. This evolvement reduced the e ect of so called \"spaghetti code\", since it allows a much more structured approach. However when talking about big software systems this alone is not a universal remedy at all. Instead of \"spaghetti code\" we now might have something like \"tortellini code\", which might be also hard to maintain. To actually manage such object oriented systems, architects again raised the level of abstraction. They often think in idioms which are conceptually above sole classlevel concepts. An evidence for this trend might be the ample success of the GoF book \"Design Patterns: elements of reusable objectoriented software\" [GHJV95]. These presented patterns respectively software patterns in general can be understood as design building blocks providing \\a proven solution to a recurring problem within a certain context\" [App00]. Such reusable mini architectures consist of a set of related participants where each one ful lls assigned responsibilities plays a certain role. In conclusion, today the collaboration aspect of a software system is a crucial factor covering all phases of a software engineering process. But what about documentation? A similar evolvement is not recog nizable. When commenting source code, programmers seem to be rather conservative. Inline source code comments which t well to the imper ative programming paradigm are still widely favored by programmers when commenting code. Indeed, commenting code using inline comments is really simple, but it currently cannot cope with the progress presented above. Due to the fact that these comments are directly attached to one particular source code fragment, their scope is limited only to the observed fragment. In particular, it is not feasible to document a program construct in context to di erent collaborations with other participating elements. Therefore, inline comments are not well suited to document collaborations adequately. Instead of inline comments, some argue that UML diagrams especially class diagrams might be a good solution to document the architecture of a software project. Obviously, they have a point, and this work does not plan to replace such diagrams. Nevertheless, class diagrams can grow up fast and are sometimes hardly traceable.
Gesamtes Dokument lesen »