Language Specification (A) : Managing Technical Debt

Managing Technical Debt

Technical debt is a metaphor for the sum total consequences of improper (software) design and implementation. Such deficiencies may be unintentional, or they may well be intentional in an attempt to shorten time to delivery. In either case, resulting deficiencies tend to accumulate over time until they reach a critical point where further development and maintenance on the software is severely impaired.

The metaphor suggests – analogous to financial debt – that (1) technical debt has to be paid down over time and with interest, and (2) interest will grow exponentially if the debt is not paid down. If technical debt is left unchecked for too long, the software may become unmaintainable. Eventually, the time and cost to reduce the deficiencies to a manageable level may vastly outpace the time and cost to rewrite the software from scratch.

In many organisations it is next to impossible to obtain the resources required to do proper maintenance on larger software projects without quantifying the debt, its financial impact and the cost required to reduce it. But without documenting the technical debt first, it is impossible to obtain that data and present figures with any confidence. Documenting and reporting of technical debt is thus a necessary prerequisite to managing the debt.

Documenting Debt

Modula-2 provides a facility to document technical debt directly within the source code. The facility is incorporated into the language syntax so that documented issues become machine readable for automated report generation. A reporting tool may then generate reports on the weight, quantity and location of technical debt within a code base directly from its source code. A simple report writer may be built into the language processor. For more complex analysis an external report writer may be used.

Syntax

A TO DO list is a machine readable directive to document technical debt directly within the source code. It may be placed wherever a definition, a declaration or a statement can occur. It may be empty, or contain a tracking reference of an external issue tracking system, and a list of tasks with descriptions and effort estimations.

toDoList := TO DO ( trackingRef? taskToDo ( ’;’ taskToDo )* END )? ;
trackingRef := ’(’ issueId ( ’,’ severity ’,’ description )? ’)’ ;
taskToDo := description ( ’,’ estimatedTime timeUnit )? ;
alias issueId, severity, estimatedTime = NumberLiteral ;
alias description = StringLiteral ;
alias timeUnit = StdIdent ; /* must be any of w, d, or h */

Reporting Debt

The language processor must report any TO DO list with line number as an informational compile time message and any syntax violation within as a compile time error. It must further report the total number of lists found in a compilation unit. Any further analysis and reporting is implementation defined. It is recommended to implement more complex analysis and reporting as a separate reporting tool outside of the language processor.

Examples

TO DO without Arguments

The arguments may be omitted from a TO DO list altogether.

PROCEDURE TitleCaseTransform ( VAR s : ARRAY OF CHAR );
BEGIN
  FOR index, char IN s DO
    TO DO
  END (* FOR *)
END TitleCaseTransform;

TO DO with Issue Tracking

A tracking reference of an external issue tracking system may be included in a TO DO list.

PROCEDURE skipBlockComment ( infile : Infile ) : Token;
  TO DO (1337, 2 (*minor*), "empty comment not recognised")
    "verify loop exit conditions", 1h;
    "fix and test", 1h
  END; (* TO DO *)
BEGIN

A tracking reference may refer to another at a different location while omitting its severity and description.

TO DO (1337)
  "Fix: move increment to the end of the loop"
END; (* TO DO *)

TO DO without Issue Tracking

The tracking reference may be omitted in a TO DO list.

TYPE DynString = POINTER TO StringDescriptor;
TO DO
  "bindings to NEW and RETAIN", 2d;
  "bindings to _ATVALUE, _ATSTORE, _LENGTH", 2d;
  "bindings to APPEND, _ATINSERT, _ATREMOVE", 3d;
  "bindings to READ and WRITE, using template", 2d;
  "unit testing", 2d
END; (* TO DO *)

Sample Report

$ m2tdr --summary --proj m2bsk
Modula-2 technical debt summary report for project m2bsk
found 14 issues with 39 tasks in 9 modules, thereof
   5 issues of weight 3 (major) with 23 tasks, est. 338 hours,
   7 issues of weight 2 (minor) with 12 tasks, est. 121 hours,
   2 issues of weight 1 (cosmetic) with 4 tasks, est. 19 hours;
found further 26 untracked tasks in 21 modules, est. 312 hours.
Total estimated effort for 65 tasks: 790 hours (avg. 12 hours/task).