Technical Debt

Technical Debt

When programmers talk in disparaging tones about “technical debt” in code, what they often mean is that the code wasn't written “properly.” A prototype got shipped long ago, and was never designed well, or in fact, was never designed at all. Some other giveaways of high technical debt are basically:

• Unit tests? That's someone else's job.
• Documentation? Never heard of it. Oh, you meant code comments? We don't use those.
• File Explorer is a source code control system.
• And a backup tool.
• Bug tracking tool? Do you mean the whiteboard?
• Requirements documentation. Also the whiteboard.
• Test plan? Eating free bananas while I test it.

Or to summarize all these points into one:

• You work at an AI startup.

Debt-Free Code: The good news is that there is a popular software development paradigm that has zero technical debt. It's called Properly-Written Code (PWC) and programmers are always talking about it in hushed or strident tones. Personally, I've been watching for years, but haven't yet been fortunate enough to actually see any, but apparently it exists somewhere out in the wild, kind of like the Loch Ness Monster, but with semicolons.

Exactly what properly-written code means is rather vague, but the suggested solution is usually a refactor or a rewrite. Personally, I favor refactoring, because I think that technical debt gets increased by rewrites, because the brand-new code:

a) Lacks unit tests.

b) Lacks internal documentation.

c) Hasn't been “tested by fire” in real customer usage.

d) Hasn't been tested by anyone, for that matter.

e) Is a “version 1.0” no matter how you try to spin it.

So, here's my probably-unpopular list of suggestions for reducing technical debt without rewriting anything:

• Comment your code!
• Fix compiler warnings to get warning-free compilation.
• Add more assertions and self-checking code.
• Check return codes from system functions (e.g. file operations).
• Add parameter validation checks to your functions.
• Add debug wrapper functions for selected system calls.
• Add automated tests (unit tests or regression tests).
• Port the platform-independent code modules to another platform. Even if only to get compiler warnings and run tests.
• Add performance instrumentation (i.e. time).
• Add memory usage instrumentation (i.e. space).
• Add file usage instrumentation.
• Document the architecture, APIs, classes, data formats, or interfaces. With words.
• Add unique codes to error messages (for supportability).
• Document your DevOps procedures.
• Run nightly builds, and with tests running, too.
• Do a backup once in a while.

And if you're at a startup or a new project, get your tools sorted out for professional software development workflows:

• Compilers and IDEs. Two is better than one.
• Memory error detection (e.g. Valgrind on Linux is my favorite)
• Source code control (e.g. SVN or git or CVS)
• CI/CD/CT build system
• Bug tracking system
• Internal documentation tools
• User support database

What really makes better code? Well, that's a rather big question about the entirety of software development practices, so I'll offer only one final suggestion: humans. My overarching view is that the quality of code is most impacted by the ability and motivation of the programmers, rather than by new tools or a trendy programming language (or even an AI coding copilot). A small team that is “on fire” can outpace a hundred coders sitting in meetings talking about the right way to do agile development processes. Hence, morale of the team is important, too.

• Next: • Up: Table of Contents • Buy: Generative AI in C++: Coding Transformers and LLMs

The new AI programming book by Aussie AI co-founders: AI coding in C++ Transformer engine speedups LLM models Phone and desktop AI Code examples Research citations Get your copy from Amazon: Generative AI in C++