Software Maintenance, Evolution, and Documentation Best Practices

Posted on Nov 29, 2025 in Software Engineering

Software Maintenance Fundamentals (Week 1)

Definition of Software Maintenance (SM)

  • “The modification to a software product after delivery to correct faults.”

Maintenance vs. Software Evolution

MaintenanceEvolution
All activities preventing failure or decay of a software system.Activities that provide new or changed functionality only.

Software Aging and Decay

  • Software ages when it does not adapt to changing technology, user needs, or competitors.

Lehman’s Laws of Software Evolution

  1. Continuing Change:
    • Real-world software (E-type systems) must keep evolving or it becomes outdated and less useful.
  2. Increasing Complexity:
    • Software gets more complex over time unless actively managed (e.g., refactoring).
  3. Self-Regulation:
    • Software evolution follows a stable pattern (release size, error rate, etc.), staying within normal ranges.
  4. Conservation of Organizational Stability:
    • The rate of work (development effort) stays roughly constant over the software’s life.
  5. Conservation of Familiarity:
    • Each update should be small to help the team remain familiar with the system.
  6. Continuing Growth:
    • New features must be added regularly to keep users satisfied and meet growing needs.
  7. Declining Quality:
    • Quality will drop over time unless the system is maintained and adapted to changes.
  8. Feedback System:
    • Software evolves based on feedback (e.g., user requests, bugs, environment changes). Evolution must respond to these inputs.

Four Types of Software Maintenance (SM)

  1. Corrective:
    • Fixing errors or faults in the system.
  2. Adaptive:
    • Changing software to adapt to changes in the environment (e.g., changes to hardware, operating system, dependencies).
  3. Perfective:
    • Changing software to evolve the functionality (adding new features).
  4. Preventive:
    • Proactive maintenance to keep the software from deteriorating (e.g., optimizations to improve scalability). This is pre-planned, not a reaction to faults.

Regression Testing

  • The process of testing to ensure no errors have been introduced when the software was modified.

Writing Maintainable Code

Principles of Maintainable Code

  1. Clean Code:
    • Readable, focused (does one thing well).
    • Efficient (reliable, fast).
    • Expressive (meaningful names).
  2. Code Smell:
    • Signs of possible design problems (e.g., duplicated code, long methods).
  3. Refactoring:
    • Improving code design without changing functionality.
    • Techniques include extracting methods and reorganizing classes.
  4. Comments & Formatting:
    • Meaningful comments explain why, not what.
    • Consistent formatting is essential.

Software Documentation and Open Source (Week 2)

Open Source Software (OSS)

Open Source Software (OSS) projects rely heavily on their communities.

Main Barriers for New OSS Contributors

  1. Reception Issues:
    • Receiving impolite, delayed, or no responses.
  2. Orientation Needed:
    • Issues include: determining which issue a newcomer should work on; inability to reproduce the issue; outdated bugs; or issues the newcomer does not understand.
  3. Documentation Problems:
    • Documentation might be lacking or outdated, negatively affecting newcomers.
  4. Cultural Differences:
    • Since OSS is global, different cultures might be involved in developing the project.
  5. Technical Hurdles:
    • Newcomers might not know the best process for contributing, including dealing with bad code quality or uncommented code. They might also struggle to set up the project environment.
  6. Newcomer Behavior:
    • Newcomers may become impatient waiting for their Pull Requests (PRs) to be checked by developers.
  7. Newcomer Previous Knowledge:
    • The newcomer’s technical knowledge, specifically whether they have or lack experience in a certain domain.

README Files: Purpose and Structure

A README contains project-related information. It should explain why the project is important, what the project can do, and how to use the project.

It is best practice to keep contribution instructions separately in a different document.

Essential README Content

  1. What does this project do?
  2. Why is this project useful?
  3. How do I get started? (Including prerequisites, installation instructions, and how to test/deploy the project.)
  4. How can the software be used? License details?
  5. What versions are available?
  6. Where can I get more help, if needed?

Note: The README should also include the tech stack and a list of major contributors.

Contributor Guidelines

  1. How to file a bug report.
  2. How to suggest a new feature.
  3. How to submit a pull request (and what happens next, like the code review process).
  4. How to set up your environment and run tests.
  5. The types of contributions the project is seeking.
  6. How newcomers can get started.
  7. Technical requirements for contributions (e.g., tests).
  8. Roadmap or vision of the project.
  9. High-level design/architecture information.
  10. Project ground rules, such as expected behavior (link to Code of Conduct).
  11. How contributors should (or should not) get in touch with maintainers.

Code of Conduct

A Code of Conduct helps set the ground rules for behavior among your project’s participants.

It is necessary to:

  • Create a welcoming, inclusive environment.
  • Set clear standards for interaction.

Software Licensing Models

  1. Public Domain: Can use and modify without restriction.
  2. Permissive: Can use and modify with minimal restrictions.
  3. GNU Lesser General Public License (LGPL): Allows linking without restriction, but modification/copying of the library itself is restricted.
  4. Copyleft: Can use and modify, but modifications must be released under the same license.
  5. Proprietary: Cannot modify or redistribute.

Bug Report Structure