source: LaTeX/CodeDocumentation.tex @ 134

Last change on this file since 134 was 134, checked in by acarter, 3 years ago

Starting code documentation latex file.

File size: 3.3 KB
3\title{Version 1.0 Code Documentation}
4\author{Andrew Carter}
7\section{Coding and Architecture Style}
8As taught in lecture (although not necessarily encouraged by the assignments our team practiced agile programming.
9    This means that our code, while working, is not necessarily the best designed in its current iteration.
10    It could probably use some refactoring, and given what we know now we may have designed things differently.
11    Of course the difference between the waterfall method and agile programming is that the design itself is living and breathing.
12    At the beginning of the semester tying ourselves to a design such as was asked in the architectural review I believe,
13        and evidence presented in lecture supports, would have led to a worse design.
14    Of course one may argue that the architectural design package and other design documents would merely be guidelines,
15        but that would lead to one of three possibilities.
16    The first is of course to literally follow the guidelines, given guidelines it is hard to pull oneself away from them, and appears to be a likely outcome.
17    Alternatively we could edit the guidelines to reflect changes as we see them, however edits are hard to keep up to date,
18        and soon we will have out of date documentation which is worse then no documentation.
19        In fact documentation of that matter is a direct violation of the DRY principle, and suffers from all of the symptoms of violations within code.
20    Instead we could use the architecture as a snapshot, however it would not be a particularly useful snapshot as it had to be done before
21        any serious coding could begin. Thus any complications of the system would not be particularly useful.
22    Thus we feel that documentation should be a part of the code, and changed with the code. Thus a change in a function should only require the comments
23        of the function to be changed, instead of another document.
24    However we realize the scale of the task to ingest new code is large, and as such we are willing to provide a snapshot document, of the high level current architecture.
25    This should be sufficient to make reasonable changes while only looking at the relevant subset of code and provided commentary.
26    Therefore related text documentation, and accompanying items like UML diagrams etc. were designed from the code,
27        instead of the other way around.
29In the general case, if there is an easy way to do things, our goal is to have that mentioned in the comments related to the change or this document.
30    However there are no guarantees of completeness, as such in attempt to catch the vast array of changes,
31        we will also go over code that is awkward to change in its current form.
32    This code works, and is ``Good enough'' in the current program.
33    But these code segments that are candidates for refactoring,
34        however we recommend against refactoring them immediately, and instead wait until the changes overly complicate the code.
35    We believe, and there is evidence from lecture to back this up, that waiting for such changes will encourage a cleaner solution.
36    Obviously how you code things is up to you.
38\section{Major Classes and their functions}
Note: See TracBrowser for help on using the repository browser.