Module 11.

Documentation and Code Maintenance

This module provides a comprehensive exploration of the integral aspects of code
documentation and maintenance. Aimed at ensuring long-term efficiency and
readability, the module addresses key topics such as organisational guidelines,
coding standards, and the application of internal documentation to code.

By the end of this module, you'll be well-versed in creating maintainable code and
understanding its documentation.

Within this module, you will learn about:

● Organisational Guidelines and Coding Standards: Focus on the

guidelines and standards that organisations typically enforce to maintain
code quality. You'll learn how these rules create a cohesive coding
environment and facilitate easier maintenance and collaboration among
team members.
● Applying Internal Documentation to Code: Explore the art and science
of embedding documentation directly within the code. This internal
documentation aims to explain complex code logic, note issues or bugs,
and provide clarifications, making the codebase much easier to
understand and maintain.
● Developing and Documenting Maintainable Code: Focuses on the
practices for writing code that not only functions optimally but is also easily
maintainable. You'll learn various techniques for writing clean,
well-documented code that stands the test of time.

You'll engage in these key learning activities:

● See why documentation is a cornerstone in software development.

Through case studies and examples, you'll see how proper documentation
can be the difference between a project’s success and failure.
● Get hands-on with documenting a specific piece of code in this activity.
You'll apply the principles you've learned to produce clear, concise, and
comprehensive documentation, making the code easier to understand and
maintain.
● Have the opportunity to exchange your documentation with peers for
review. This peer review process will help you gain different perspectives
on your work and learn ways to improve its clarity and completeness.

Subject Learning Outcomes

The material in this module relates to the following subject learning outcomes:

​ SLO 7: Understand the importance of and become proficient in creating

comprehensive documentation for code and software, and learn the
principles of quality assurance for software compliance.

Student Expectations

During this module, you are expected to spend time working through the prescribed
material prior to attending class. This will enable a more valuable discussion to take
place in online tutorials or conferences, where you will be able to discuss concepts,
present ideas and explore information collaboratively in greater depth.

Accordingly, it is suggested that you allow:

4 hours for facilitated study. This includes guided facilitated study, watching or
attending course lectures (live or pre-recorded), and responding to facilitator
feedback.

8 hours for personal study. This includes reading through course material,
undertaking learning activities and exploring additional related resources.

Topic 1. Organisational Guidelines and Coding

Standards

Key takeaways from this topic...

 1. Adhering to organisational guidelines and coding standards ensures
consistency across the codebase, making it easier to read and maintain.
2. Standards and guidelines facilitate quicker onboarding of new developers, as
they provide a set structure and style to follow.
3. A standardised approach to coding can enhance the overall quality of the
software and ease the process of debugging and updating.

Learner Guide

The Learner Guide provides the core knowledge for this topic. Work through the
materials and be prepared to discuss these in your forums, tutorials or classes.

Expand All

Panels

Collapse All

Panels

Section 1: Introduction to Organisational Guidelines and Coding Standards

In the profession of software development, adhering to organisational guidelines and

coding standards is not merely a formality but a pathway to fostering seamless
collaboration and enhancing code maintainability. These guidelines are fundamental
in ensuring a uniform approach to coding which aids in streamlined project progress
and successful outcomes. Let’s delve into the intricate realms of these guidelines
and standards to understand their pivotal role in the software development lifecycle.

Importance of Organisational Guidelines

Organisational guidelines serve as a blueprint for streamlining processes and
cultivating a culture of excellence within a development team. These guidelines help
in formulating realistic and beneficial rules that guide the team’s efforts towards
achieving project goals with proficiency and coherence.

Understanding Coding Standards

Coding standards are the backbone of proficient software development. Abiding by

these standards not only facilitates readability but also simplifies the maintenance
process. These standards primarily encompass various aspects such as adopting
suitable naming conventions, structuring code logically, and incorporating relevant
comments and documentation to aid future references and modifications.

Further Reading

Coding Standards and Guidelines

Links to an external site.

Explore the benefits of adhering to coding standards, such as promoting sound

programming practices, facilitating code reuse, and improving efficiency. Specific
coding standards mentioned include limited use of globals, standard headers for
modules, naming conventions for variables and functions, proper indentation, and
error return values.

Reference: Geeks for Geeks, n.d., 'Coding Standards and Guidelines', Geeks for Geeks, accessed 31
January 2024, <https://www.geeksforgeeks.org/coding-standards-and-guidelines/>

Section 2: Practical Application of Guidelines and Standards

To translate the theory into practice, it’s imperative to engage in real-world
applications. Here, we will explore how to practically apply the discussed concepts in
a work environment:

● Drafting Guidelines
As a starting point, consider drafting a set of guidelines that align with the
organisational goals and foster a harmonious working environment.
● Implementing Coding Standards
Once familiar with the coding standards, focus on implementing these
diligently in your projects to witness the transformation it can bring in terms
of readability and maintainability.

Section 3: Case Study - Implementing Organisational Guidelines and Coding

Standards

Scenario

You are a team member in this dynamic environment. The leadership decides that
it's time to bring a change to uplift the code quality and team collaboration. The
objective is clear: To create a well-structured, maintainable, and uniformly styled
codebase that would streamline the workflow and enhance productivity.

Steps Taken

● Setting Up a Committee
A committee comprising senior developers and project managers was set
up to draft the organisational guidelines and coding standards. They were
tasked with researching and proposing a set of rules that would be both
modern and easy to adopt.
● Drafting the Guidelines
The committee worked diligently to draft comprehensive guidelines that
encompassed best practices in coding, including naming conventions, file
 organisation, and commenting. These guidelines were built keeping in
mind the existing challenges and potential growth of the firm.
● Training Sessions
Once the guidelines were drafted, a series of training sessions were
organised. These sessions were interactive, providing team members with
the opportunity to understand the new standards and how to implement
them in their daily workflow.
● Implementation
After the training sessions, the team began to implement the new
standards. A grace period was provided to allow team members to adapt
to the new norms. Peer reviews were encouraged to foster a collaborative
learning environment.
● Feedback and Adjustments
Over time, feedback was collected from the team members about the new
guidelines. Necessary adjustments were made to ensure that the
standards were both efficient and user-friendly.

Outcome

1. Enhanced Code Quality

With the adoption of the new standards, the codebase transformed into a
more structured and readable form. This facilitated easier maintenance and
modifications.
2. Improved Collaboration
The uniform coding style fostered better collaboration among team members.
Code reviews became more productive, with team members being able to
understand and critique each other’s code more effectively.
3. Boosted Morale and Productivity
The clear guidelines and standards uplifted the team’s morale. They now had
a clear roadmap to follow, which eliminated confusion and boosted
productivity.

Conclusion

This case study illuminates the transformative power of implementing organisational

guidelines and coding standards within a software development team. Not only did it
streamline the workflow, but it also fostered a culture of collaboration and excellence,
setting a foundation for the firm's future success.

Learning Activity - Importance of Documentation in

Software Development

Activity Type: Theoretical Study and Group Discussion

Time on Task: Approx. 60 mins

Instructions:

1. Study provided materials or search for articles, papers, and case studies
emphasising the importance of documentation in software development.
2. Prepare a list of key takeaways and reasons why documentation is crucial.
3. In a group setting, discuss your findings and relate them to your own
experiences or projects you're familiar with.
4. Write a summary of the discussion, highlighting the main points and
conclusions reached.

Topic 2. Applying Internal Documentation to Code

Key takeaways from this topic...

1. Good internal documentation makes the code self-descriptive, reducing the

cognitive load on developers trying to understand it.
2. Well-documented code stands the test of time, making it easier to maintain
and update in the future.
3. Effective internal documentation can help in reducing errors, as it provides
contextual information that aids in understanding the code’s functionality and
limitations.
 Learner Guide

The Learner Guide provides the core knowledge for this topic. Work through the
materials and be prepared to discuss these in your forums, tutorials or classes.

Expand All

Panels

Collapse All

Panels

Section 1: Importance of Internal Documentation

In software development, internal documentation serves as a road map that guides

developers through the intricacies of the codebase. It facilitates better understanding
and smoother transitions throughout the lifecycle of a project. This topic will walk you
through the essential aspects of applying internal documentation to your code,
offering both theoretical knowledge and practical strategies to enhance your
documentation skills.

Understanding the significance of internal documentation is the first step in adopting

good coding practices. Effective documentation aids in:

● Simplifying Code Navigation

Developers can quickly locate and understand specific segments of the
code.
● Facilitating Collaboration
A well-documented codebase makes it easier for teams to work together.
● Streamlining Debugging
With clear documentation, identifying and resolving issues becomes more
efficient.
● Ensuring Continuity
Detailed documentation ensures that the project can be easily managed
 and extended in the future, even if the original developers are no longer
involved.

Section 2: Strategies for Effective Documentation

Here, we delve deeper into the methodologies and strategies to craft insightful and
useful documentation.

● Comments
Incorporate various forms of comments within your code to convey the
function and purpose of different code sections.
● Descriptive Naming
Choose appropriate and descriptive names for variables, functions, and
classes.
● Maintaining a README File
Maintain a comprehensive README file that encompasses a project
overview, setup instructions, and guidelines.
● API Documentation
Document the API usage thoroughly, offering endpoint descriptions and
examples.
● Change Logs and Version Control
Employ version control systems like Git to track alterations and manage
different versions of the project.
● Including Code Examples
Provide insights through code examples in the form of tutorials or code
snippets.
● Error Handling and Reporting
Develop a robust system for error handling and reporting, incorporating
descriptive error messages and maintaining error logs.

Section 3: Case Study - Enhancing Project Readability through Improved Internal

Documentation

Background
In the heart of a rapidly expanding tech start-up, a group of ambitious developers
embarked on a mission to create a pioneering web application aimed at
revolutionising e-commerce operations. The initial phases of the project were
marked by enthusiasm and rapid development. However, as the team expanded and
the project became more complex, it became apparent that the codebase lacked
sufficient documentation. This gap in internal documentation began causing delays
and confusion, particularly for new members who found it challenging to navigate
and comprehend the project's intricacies.

Scenario

You, having a substantial experience and understanding of the project, are appointed
to lead an initiative to bolster the internal documentation. This task is not only vital to
streamline the ongoing development process but also seen as a strategic move to
set the stage for the project's future scalability and sustainability. The primary
objective is to transform the codebase into a well-documented repository that can
facilitate smoother collaboration and expedite the project’s progression.

Action Plan

To navigate this challenge, you proposed a comprehensive action plan that involved
several strategic steps:

1. Analytical Review of the Current Codebase

Conduct a meticulous review of the existing codebase to pinpoint areas where
documentation was sparse or unclear. This would involve collaborative
feedback sessions with various team members to gather insights into the
current challenges.
2. Developing a Documentation Blueprint
Create a blueprint that outlines the essential documentation elements
required at different levels of the code. This would serve as a guide for the
team to follow during the documentation enhancement process.
3. Revamping Naming Conventions
Initiate a revision of the existing naming conventions, encouraging the use of
 descriptive names that delineate the purpose and functionality of different
code elements clearly, thereby avoiding ambiguity.
4. Creating a Comprehensive README File
Craft a detailed README file that encapsulates critical project information,
setup instructions, and contribution guidelines, serving as a central resource
for team members and future contributors.
5. Enhancing API Documentation
Dedicate efforts to enrich the API documentation with clear endpoint
descriptions and practical examples, fostering a user-friendly approach to
interacting with the API.
6. Implementing Error Handling Strategies
Develop robust error handling and reporting strategies, incorporating
descriptive error messages and systematic error logs that streamline the
debugging process.
7. Incorporating Practical Code Examples
Integrate detailed code examples into the documentation to illustrate the
practical usage of various functions and classes within the project, fostering a
deeper understanding and hands-on familiarity with the code.
8. Training and Knowledge Sharing Sessions
Organise regular training sessions where team members can learn about the
new documentation standards and share insights and suggestions to enhance
the documentation further.

Outcome

The concerted effort to improve internal documentation bore significant results:

1. Streamlined Collaboration
Team members found it easier to collaborate, with clear documentation
reducing misunderstandings and facilitating more productive discussions.
2. Accelerated Debugging Processes
The introduction of systematic error handling and reporting strategies made it
easier to identify and resolve issues swiftly, reducing the time spent on
debugging.
3. Enhanced Onboarding Experience
New members could onboard more seamlessly, with the enhanced
documentation providing a clear roadmap to navigate the project's
complexities.
Topic 3. Developing and Documenting Maintainable
Code

Key takeaways from this topic...

1. Code that is both maintainable and well-documented is more scalable,

allowing for easier feature additions and modifications.
2. Prioritising documentation and maintainability can significantly reduce
technical debt over time.
3. Maintainable, well-documented code aids in efficient knowledge transfer
among developers, making team collaborations smoother.

Learner Guide

The Learner Guide provides the core knowledge for this topic. Work through the
materials and be prepared to discuss these in your forums, tutorials or classes.

Expand All

Panels

Collapse All

Panels

Section 1: Strategies for Developing Maintainable Code

In the swiftly evolving sphere of software development, crafting maintainable code is

a cornerstone of successful and sustainable projects. Such an approach not only
eases transitions between various development phases but also ensures effortless
management and adaptation of code in the future. In this segment, we shall delve
deep into strategies pivotal in developing and documenting maintainable code, and
illustrate these principles through a real-world case study.

Strategies for Developing Maintainable Code

● Code Consistency
○ Coding Conventions
○ Code Linting
● Modular Design
○ Decomposition
○ Encapsulation
● Code Comments and Documentation
○ Inline Comments
○ API Documentation
● Version Control
○ Branching Strategy
○ Change Tracking
● Code Reviews
○ Peer Reviews
○ Automated Code Analysis

Section 2: Enhancing Maintainability in a Financial Software System

Background

In a thriving financial firm, the software team was grappling with growing challenges
emanating from an outdated software system. As the firm expanded and
incorporated new members, the inconsistencies in coding standards and sparse
documentation became evident. This scenario not only hampered the onboarding
process but also decelerated the enhancements needed to meet the business's
evolving needs. Identifying this bottleneck, the leadership decided to strategically
revamp the system to bolster maintainability and scalability.
Initial Challenges

● Inconsistent Coding Styles

Various sections of the code were developed by different individuals over
the years, leading to a disparity in coding styles and standards.
● Outdated Documentation
The existing documentation was obsolete, not encompassing the system's
current functionalities, thus posing a significant barrier for newcomers to
comprehend and work on the system.
● Monolithic Architecture
The system adhered to a monolithic architecture, which complicated the
integration of new features or modifications without affecting other
components of the system.

Strategies Implemented

● Coding Standards
The journey commenced with the formulation of comprehensive coding
standards. These norms were meticulously documented and disseminated
throughout the organisation, encouraging a uniform approach to code
development.
● Documentation Overhaul
A dedicated task force undertook the mission to revamp the existing
documentation. This team collaborated closely with veteran members to
develop detailed and contemporary documentation, elucidating the various
system modules clearly and providing guidelines and best practices for
interacting with them.
● Modular Approach
A structural shift to a modular design ensued. Each module was
engineered to handle specific functionalities, fostering easier management
and facilitating potential extensions in the future.
● Version Control and Code Reviews
A robust version control system was instituted to efficiently manage
diverse versions of the code. Regular code reviews became a norm,
aiding in maintaining code quality and fostering knowledge transfer among
team members.
Outcome

The strategic implementations metamorphosed the software system into a more

manageable, maintainable, and scalable entity. New team members could be
onboarded more swiftly, guided by clear documentation and coding standards.
Moreover, the modular structure allowed for faster and more secure feature
deployments, augmenting the system's adaptability and efficiency.

Further Resources
The resources in this section are for further exploration, providing additional
information for deeper insights.

Expand All
Panels
Collapse All
Panels
Reading: Coding Standards and Best Practices to Follow
Coding standards are a set of guidelines and best practices that are used to create
consistent, high-quality code. Consider coding standards as rules, techniques, and
best practices to develop cleaner, more readable, and more efficient code with
minimal errors. They offer a uniform format for software engineers to build
sophisticated and highly functional code.

This article covers the advantages/purpose of maintaining coding standards in

software engineering and discusses 8 coding practices for writing and running clean,
correct code that delivers accurate and relevant results.

Coding Standards and Best Practices to Follow

Links to an external site.

Reference: Shreya Bose (Community Contributor), 2023, 'Coding Standards and Best Practices to
Follow', Browser Stack, accessed 31 January 2024,
<https://www.browserstack.com/guide/coding-standards-best-practices>

Reading: Coding Standards for Quality and Compliance

This article discusses the importance of coding standards in preventing coding
defects, ensuring compliance with industry standards, maintaining consistent code
quality, enhancing software security, and reducing development costs.
Coding Standards for Quality and Compliance

Links to an external site.

Reference: Perforce, n.d., 'Coding Standards For Quality and Compliance', Perforce, accessed 31
January 2024, <https://www.perforce.com/resources/qac/coding-standards>

Video: How to Document Your Code Like a Pro

This video explores the essential principles for creating clear, concise, and effective
code documentation. From commenting to docstrings, you’ll learn how to make your
code documentation shine and improve accessibility for others.

How to Document Your Code Like a Pro

Links to an external site.

(19:03)

Reference: ArjanCodes, 2023, 'How to Document Your Code Like a Pro', YouTube, accessed 31
January 2024, <https://youtu.be/L7Ry-Fiij-M>

Reading: Google C++ Style Guide Overview

A code style guide is a guide to what your source code should look like. It defines the
appearance of the source code. It's important that you format your source code
according to the style guide suggested by the project.

The Google C++ coding style has become very popular and some highlights are
featured in this article.

Google C++ Style Guide Overview

Links to an external site.

Reference: Eric Gregori, 2021, 'Google C++ Style Guide Overview', LinkedIn, accessed 31 January
2024, <https://www.linkedin.com/pulse/google-c-style-guide-summary-eric-gregori/>

Reading: Google C++ Style Guide

C++ is one of the main development languages used by many of Google's
open-source projects. As every C++ programmer knows, the language has many
powerful features, but this power brings with it complexity, which in turn can make
code more bug-prone and harder to read and maintain.

The goal of this guide is to manage this complexity by describing in detail the dos
and don'ts of writing C++ code. These rules exist to keep the code base manageable
while still allowing coders to use C++ language features productively.
Google C++ Style Guide

Links to an external site.

Reference: Google, n.d., 'Google C++ Style Guide', GitHub, accessed 31 January 2024,
<https://google.github.io/styleguide/cppguide.html>