3.4.4 - Formative project skills: maintenance and further development

Explain how the structure affects future changes

Maintainability is how readily a solution can be understood, corrected and adapted without introducing unintended faults. It is a property to explain using the actual structure and supporting evidence, rather than a label earned by calling the code “modular”.

In a miniature event-registration tool, separate responsibilities might include collecting a form entry, validating the group size, storing an accepted booking and displaying the outcome. If both new-booking and amendment journeys call the same validation routine, a change to the permitted size has one rule implementation to update. If each screen contains its own copy, a maintainer may change one and leave the other inconsistent.

Modularity helps when boundaries are sensible. Splitting every statement into a tiny function can make a simple journey harder to follow, while hidden shared global state can couple routines despite separate names. Explain where data flows and which callers a change affects. A routine that changes both the size and the saved records has a wider impact than a routine that only returns a validation result.

Support the judgement with relevant code excerpts, known callers and test evidence. “The shared validator is used by both entry paths, so one rule change can be retested through both paths” explains a concrete advantage. “There are functions, therefore maintenance is easy” does not establish useful boundaries or safe change.

Give maintainers the information needed to work safely

Useful maintenance documentation explains the decisions and interfaces that a future maintainer cannot reliably infer from a quick reading. Record how to set up the development environment, the relevant dependencies and versions, routine contracts, data meanings and repeatable tests. Keep these records aligned with the actual final implementation.

In-code comments should explain non-obvious purpose or constraints. A comment saying “add one” beside an addition adds little; explaining that a stored counter excludes cancelled bookings helps a maintainer avoid changing its meaning. The current project guidance expects code annotation itself to aid maintenance, not just screenshots of uncommented code with explanations in a separate report.

For a saved-booking field status, describe the permitted values, what each means and which transitions are valid. If an old record can use cancelled, a new importer must not silently treat it as an active booking. For a library dependency, record its role and the actual version used; a future update may change behaviour even if your own source is unchanged. Do not assume the course's console can execute every GUI library or database integration; those maintenance checks belong in the actual external development environment.

Repeatable regression tests give the maintainer a baseline before and after a change. Identify required data fixtures, setup and expected outcomes rather than writing “run the tests”. A test record for both Create and Amend reveals whether the shared rule is used consistently. Tests assist understanding and detection; a passing selected suite still has a coverage limit.

Good documentation can also expose limitations. If no one recorded how to rebuild the GUI environment, another developer may struggle to reproduce a fault. If comments contradict the code, they mislead. Assess both the useful information and the gaps instead of assuming a long document is adequate.