Internal documentation in an Elucidative environment
Authors
Andersen, Max Rydahl ; Sørensen, Kristian Lykkegaard ; Christensen, Claus Nyhus
Term
4. term
Education
Publication year
2000
Abstract
Dette speciale undersøger, hvordan programmører skriver og organiserer intern dokumentation—de noter og forklaringer, som udviklere laver til hinanden for at beskrive programmets indre funktioner, fx algoritmer og datastrukturer—og hvordan dokumentationens historie kan indfanges i et udviklingsmiljø, der lægger vægt på tydelige forklaringer (et elucidativt miljø). Specialet bidrager med tre ting: (1) Det præsenterer MRS-modellen, som opdeler intern dokumentation i tre sammenhængende kategorier: Motivationer (mål og kontekst bag koden), Begrundelser (årsagerne til designvalg) og Løsningsbeskrivelser (hvordan den valgte løsning realiseres i koden). (2) Det viser en praktisk implementering af modellen i et elucidativt miljø. (3) Med MRS-modellen skitserer det en metode til at dokumentere historikken for både intern dokumentation og kildekode som en naturlig del af den interne dokumentation. På den baggrund konkluderes, at MRS-modellens struktur gavner den interne dokumentation og forbedrer dens præsentation for læseren, og at softwarehistorik kan dokumenteres som en integreret del af den interne dokumentation.
This thesis examines how programmers write and organize internal documentation—the notes and explanations developers create for each other to describe a program’s inner workings, such as algorithms and data structures—and how the history of that documentation can be captured in a development setting that emphasizes clear explanations (an elucidative environment). It makes three main contributions: (1) It introduces the MRS-model, which groups internal documentation into three connected categories: Motivations (the goals and context behind code), Rationales (the reasons for design choices), and Solution descriptions (how the chosen solution is implemented in code). (2) It demonstrates a practical implementation of this model within an elucidative environment. (3) Using the MRS-model, it outlines a method for documenting the history of both internal documentation and source code as a natural part of the internal documentation. Based on these contributions, the thesis concludes that the MRS-model improves the structure and presentation of internal documentation for readers, and that a software system’s history can be documented as an integrated part of that documentation.
[This abstract was generated with the help of AI]
Documents