In the arcane and convoluted realm of software engineering, time and scope are factors of paramount importance. Designing application solutions with a view towards time and scale is vital to ensure that the software is both sturdy and adaptable in the long run.
These are not consideration that you need to worry about when flying solo or working with small or short lived projects, but in big teams and in projects which are supposed to last for a long time, you always have to think about the future.
The Bus Factor
The bus factor is a telling metric of the vulnerability of a software project, reflecting the number of individuals who would have to suffer a fatal mishap before the project would be in peril. The higher the bus factor, the more resilient the project is, as it relies on a broader and more diverse pool of expertise. It simple terms, it is the number of people that would have to be hit by a bus before the project would be in trouble, or in other words, the number of people that detain the knowledge of how the software works.
This highlights the indispensable value of team dynamics and knowledge sharing in software engineering, where the collective wisdom and expertise of the team members can ensure that the project remains resilient and relevant through personnel changes and the vagaries of time.
I have been onboarded to projects where the bus factor was 1! It was an old legacy project that had been developed by a single person, and that person was about to leave the company. My job was to navigate through a maze of undocumented code and try to understand how the software worked. There was no documentation, no tests, no nothing. It was a nightmare. The guy was still around for consulting, but since he was the only one with the knowledge of how the software worked, he could behave very leniently, sometimes taking multiple days to answer simple questions. The client simply couldn't fire him before I had a good grasp of the project or it would stop in production.
Passing Knowledge Through Time
Documentation
Documentation is a fundamental tool for passing knowledge through time, providing a written record of the project's design, implementation, and maintenance that can be accessed and understood by new team members. Well-crafted documentation should be lucid, succinct, and exhaustive, covering all aspects of the project's lifecycle, from the initial concept to the final implementation. It can take many forms, such as user manuals, technical specifications, design documents, and more. Good documentation helps new team members quickly grasp the project's goals, requirements, and technical intricacies, reducing the learning curve and enabling them to contribute more effectively to the project.
The simplest method of documentation is a README file in the root of the project. This file should provide an overview of the system, its architecture, and its dependencies. It should also include instructions for installing and running the software, as well as troubleshooting tips and common issues. README files can be especially useful for open-source projects, where many developers may be working on the same codebase at different times. In fact, a good rule is: treat all projects as if they were open source. This will ensure that you always have good documentation.
Another way to document software is to use inline comments in the code itself. There is a long discussion on where code should be self documenting, but I believe that sparse commenting is always a good idea. Comments should be used to explain the reasoning behind a particular design decision or to clarify the purpose of a complex function or algorithm. They should not be used to explain what the code is doing, as this should be evident from the code itself. Comments should also be kept up-to-date, as outdated comments can be misleading and confusing to new team members.
User manuals and other forms of end-user documentation can also be valuable, particularly for software that is intended for a broader audience. These documents should be written in a way that is easy for non-technical users to understand and provide step-by-step instructions for using the software. They can also include troubleshooting tips and common issues that users may encounter.
For larger projects, a more robust way is necessary. Some common methods include using a wiki, a knowledge base created in apps like Google Docs or Notion, or a project management software. These tools can be used to store and organize information about the project, including design documents, technical specifications, and user manuals.
Code Best Practices
Code best practices are another potent method of passing knowledge through time, as they make the code more comprehensible without the need for extensive documentation. This includes using clear and meaningful variable and function names, following established naming conventions, and avoiding overly intricate coding structures. These best practices help ensure that the code adheres to the team's coding standards and is more accessible to new team members. The use of linters can also help maintain a consistent codebase and highlight potential issues and inconsistencies, further reinforcing the code's maintainability and longevity.
Project Management Software
Project management software is a vital tool for keeping a history of the codebase development. It provides a centralized repository of project-related information and facilitates collaboration and communication. Effective project management software can serve as a record of the team's brainstorming sessions, decision-making processes, and implementation strategies, enabling new team members to familiarize themselves with the project's context and history quickly. Some popular examples of project management software include Asana, Trello, and Jira, each with their unique features and strengths.
Conclusion
Passing knowledge through time in software engineering is a necessary skill that can be achieved through methods such as documentation, code best practices, linters, and project management software. Think of your project not only as a bunch of code, but as a tool that will outlive you and will be used by other people. Registering the precious knowledge that your team has acquired through time is not only advisable, but in fact is part of your job as a software engineer. You are not only responsible for designing an application for now, but for the future as well.