Software Engineering 102: Documentation, Testing and Technical Debt

Published on: 16-11-2023

1. Document your progress

There are several types documentation you can employ while working on a project:

• comments in your code,
• commit messages,
• project notes,
• user manuals.

Documentation helps you and your team avoid mistakes and identify patterns. Both are beneficial to improve future work and streamline collaboration.

Use comments whenever code becomes less obvious. You should already be using relevant variable and function names, but it also helps when you add a comment or two that explain the goal of a section of code.

Make sure to update in-line comments over time, while working on the code, to keep them relevant.

2. Test often

This one counts for half a practice. Grown-up programmers don't need tests - they write perfect code! But seriously, testing can expose issues early on during development and can ensure that finalized features work as intended. Manual testing is still welcome, but it often can't emulate all fringe cases and may take more time than is available before deadlines come up. Continuous testing is an essential component development that can help in delivering frequent, high-quality software.

3. Don’t lose control of technical debt

Technical debt is the result of focusing too much on fast delivery and not enough on code quality. Clients will often impose short deadlines, forcing developers into taking shortcuts with their code. While the feature is delivered on time, the shortcuts will be an increasing problem in the future. As the software grows, the problems grow with it, until something snaps. It’s only then that developers find that serious bugs, legacy code and missing documentation prevent them from moving forward.

With the above in mind, we must also say that the impact of technical debt is relative to its context. In some projects it might not be critical, but striking a balance between rapid delivery of code and regular revisions of the code itself and its related items can benefit you in the long run.

Why work with Apidemia on this?

Twenty years of PHP, and we're an official Laminas commercial vendor - one of a short list endorsed by the technology's own stewards. Most of our engineers are ZCE (Zend Certified Engineers). We build for the long term - projects that don't need a rewrite again in three years.

Talk to us about your platform.