5. Documentation and Version Control

24/10/21

Documenting Code

Code comments are essentials for maintenance as they are key to having another person be able to understand what you have done
Semi-Automatic documentation enables:
- Standard comment formatting and structure
- Less typing, some automation
Examples include Doxygen and Javadoc.

Many tools are build into IDEs, it is great for helping create maintainable code including in-built testing help
Javadoc is great for java documentation. This comes with JDK and requires you to tag your code with special comments

@<tag> - Syntax. Generates easy to use HTML based output as a living document.Updated each compile time. Useful tags:

Ability to recover old versions and examine source code history
Works across networks (fosters collaboration)
Similar with a networked file system + backup + additional functionality.
Repository: Stores a file system tree. Remembers every change ever written to it
Concurrency Management: Simultaneous occurrence; coincidence. Ways to deal with concurrency:
- Problem of file sharing
- Lock-modify-unlock solution
- Copy-modify-merge solution
Lock-Modify-Unlock Solution: Serialisation. There is no protection for breaking dependencies between files. False sense of security

Copy-modify-merge model: for text files
- Users work in parallel
- Concurrent changes are automatically merged
- Conflicts can generally be managed
The lock-modify-unlock model: for all types

Regular directory tree
It does not unless specifically told:
- Incorporate others people changes
- Make your own changes available to others
A typical repository = severl projects
Each project = subdirectory