Technical Debt: Fixing Missing API Documentation

Introduction

In any software project, technical debt is an unavoidable reality. It represents the implied cost of rework caused by choosing an easy solution now instead of using a better approach that would take longer. This article delves into a specific instance of technical debt concerning missing documentation for 1907 public API items within a project. We'll explore the impact of this technical debt, the modules affected, the decision-making process behind addressing it, and the proposed solutions for resolving the issue incrementally.

Understanding the Problem: 1907 Missing API Documentations

The project in question has a significant amount of missing rustdoc comments, specifically 1907 items. These missing comments trigger clippy quality gates, which in turn, prevent production deployments. Clippy is a Rust linter that helps catch common mistakes and improve code quality. One of its checks is to ensure that all public API items have proper documentation. When this check fails, it blocks the continuous integration and continuous deployment (CI/CD) pipeline, hindering the release process.

The Impact of Missing Documentation

The impact of missing documentation is multifaceted:

• Blocks CI/CD: The most immediate impact is the blocking of cargo clippy --lib -- -D warnings, a crucial step in the CI/CD process.
• Scope: The issue spans across 1907 public API items, indicating a widespread problem.
• Strategic Technical Debt: This is classified as strategic technical debt rather than a code defect. It means the missing documentation doesn't directly cause functionality issues but impacts maintainability and understandability.

Modules Affected by the Documentation Gap

Based on the clippy output, several modules are significantly affected by the missing documentation:

• rash/src/ast/restricted.rs: This module, containing AST types, is the most affected.
• rash/src/bash_parser/ast.rs: The Parser AST module also lacks sufficient documentation.
• rash/src/linter/*: The linter modules are missing necessary comments.
• rash/src/validation/*: Similarly, validation rules require better documentation.
• rash-runtime: The runtime crate has a few undocumented items.
• Multiple other modules across the project.

The Toyota Way: Triage Decision

When faced with technical debt, it's crucial to make informed decisions about how and when to address it. In this case, the project team employed a triage approach inspired by the Toyota Way, a set of principles and practices focused on continuous improvement and problem-solving. The key question was whether the missing documentation was blocking production.

Why It's Not Blocking Production (Currently)

Despite the large number of missing documentation items, the team determined that it wasn't directly blocking production for several reasons:

1. All Code Quality Checks Pass: Clippy runs without the -D missing_docs flag, ensuring that other critical code quality checks are passing.
2. All Tests Passing: The project has a robust test suite with 6861 tests, all of which are passing, indicating functional stability.
3. Zero Functional Defects: No functional defects have been identified, suggesting that the missing documentation doesn't directly impact the application's functionality.
4. Strategic Debt, Not a Defect: The missing documentation is considered strategic technical debt, which means it impacts long-term maintainability and understandability rather than causing immediate operational issues.

Separating from Quality Gates to Unblock Progress

The decision was made to separate the missing documentation issue from the quality gates to unblock progress on other critical tasks. This allowed the team to focus on addressing immediate concerns while planning for the documentation effort. Specifically, this decision unblocked:

• Issue #43: DET002 false positive fix
• Issue #23: Inline suppression support
• Issue #13: FROM scratch Dockerfile scoring

Proposed Solution: A Phased Approach

To tackle the technical debt of missing documentation, a phased approach was proposed. This allows for incremental progress and avoids overwhelming the team with a massive documentation effort.

Phase 1: Remove from Blocking Gates (URGENT)

The first and most urgent step was to remove -D missing_docs from the Cargo.toml workspace lints. This action unblocks the CI/CD pipeline, allowing for production deployments and continued development without being blocked by the documentation check. This doesn't mean documentation is ignored; it simply shifts the focus to a more manageable, incremental approach.

Phase 2: Incremental Documentation (Backlog)

This phase focuses on gradually adding documentation over multiple pull requests (PRs). The key steps include:

1. Start with Most-Used Public APIs: Prioritize documenting the most frequently used public APIs, such as those in the linter and parser modules. This ensures that the most critical parts of the codebase are well-documented first.
2. Document New Code as It's Added: As new code is written, documentation should be included as part of the development process. This prevents the accumulation of further technical debt.
3. Add rustdoc Enforcement for New Modules Only: Introduce rustdoc enforcement for new modules. This ensures that all new code has the required documentation from the outset.
4. Gradually Expand Coverage: Over time, expand the documentation coverage to include less frequently used APIs and older modules.

Phase 3: Tooling (Future)

This phase explores the use of tooling to help track and manage documentation efforts. The proposed steps include:

• Add cargo doc --no-deps to CI: Integrate cargo doc --no-deps into the CI process to generate documentation and check for warnings (but not errors). This provides early feedback on documentation issues.
• Track Documentation Coverage Over Time: Implement a system to track documentation coverage over time. This provides visibility into the progress of the documentation effort and helps identify areas that need attention.
• Require Docs for New Public APIs: Enforce a requirement for documentation for all new public APIs. This helps prevent the accumulation of further technical debt.

Non-Goals: Avoiding Common Pitfalls

To ensure the success of the documentation effort, it's important to define what the project will not do. The following non-goals were established:

• ❌ Block All Work Until 1907 Items Documented: This approach is unrealistic and would halt development for an estimated 8-12 hours, which is unproductive.
• ❌ Rush Documentation Without Quality: Rushing the documentation process would likely result in low-quality documentation that is unhelpful and potentially misleading.
• ❌ Allow New Undocumented APIs: Preventing the creation of new undocumented APIs is crucial to avoid further increasing technical debt.

References: Supporting Information

• Clippy output: 1907 errors, all "missing documentation"
• Code quality: CLEAN (passes clippy -A missing_docs)
• Test coverage: 6861 tests passing

Priority and Effort Estimation

The missing documentation issue is assigned a priority of P2, indicating that it's technical debt that needs to be addressed but isn't immediately critical. The estimated effort to complete the documentation is 8-12 hours in total, spread across multiple PRs. This phased approach allows the team to manage the effort effectively without disrupting other development activities.

Conclusion: A Commitment to Quality and Maintainability

Addressing technical debt, such as missing documentation, is crucial for maintaining the long-term health and maintainability of a software project. By adopting a phased approach and prioritizing incremental improvements, the project team can effectively tackle the issue without disrupting ongoing development. This commitment to quality and maintainability ensures that the project remains healthy and sustainable in the long run.

For more information on managing technical debt, you can visit Martin Fowler's website, a trusted resource in the software development community.