Thoughts of a software developer – How to build extendable software
Imagine you are starting to work for a customer who has an existing software system that needs to be extended. On your first day at the customer you want to quickly understand the existing piece of software. So you start your favorite IDE and check out the project from Git or Subversion. You are trying to run the project but nothing happens and you are still trying to get anything running but nothing happens again. You are getting frustrated. This blog entry should help you avoid getting others in this situation. But this blog entry is also useful for software architects that need to work with external or newly hired software developers. This blog entry is not so technical, but it is more about how to build software that can easily be extended by new developers.
The topics of the blog are:
- Write JavaDoc (even if it is boring)
- Use technologies that are accepted (even if they are not the best fit)
- Have documentation (but not too much)
- Use graphics (says more than 1000 words)
- Keep it simple (don’t add complexity)
- Conclusion
Write JavaDoc (even if it is boring)
To help external and newly hired developers to understand the existing software, the software should contain JavaDoc. I don’t mean that every function should be documented (e.g. getters and setters), as this would not be very helpful. But the important parts of a software system should have JavaDoc. That helps the external developers to understand the functions, how to use them, and it is faster than to analyse the code.
Use technologies that are accepted (even if they are not the best fit)
When you are the architect of a piece of software, you should keep in mind to use technologies that are accepted by a big group of developers. The best technology can be useless if only a handful of people know how to use it. So compare different technologies and find one that solves your problem but is also used by a bigger group of developers. That can have a huge impact on the mood of your developers and how quickly they can get up and running.
Have documentation (but not too much)
General documentation is not only useful for your customers but also for developers. The general documentation helps developers to understand the domain better. But keep in mind that documentation of 100 pages is (most of the time) too much. The documentation should be small and have the key features explained comprehensively. Even better than text is to use graphics that describes the workflow. Most of the time a graphic says more than 1000 words. Furthermore, provide an overview of the domain terminology and explain the meaning of these terms.
Use graphics (says more than 1000 words)
Similar to documentation, it helps to provide graphics that are providing an overview of the software. The graphics don’t need to conform to a standard (e.g. UML) but they should show the important parts of the software and its inner workings. Most developers know how to read a graphic and you don’t need to explain a lot about it. If they have questions they will come to you for a more detailed explanation. A graphic can even help you to identify dirty constructs in a piece of software and help you to find a solution on how to avoid them.
Keep it simple (Don’t add complexity)
I cannot stress this enough: you should keep your software simple. If it gets to complex think about how to reduce complexity. If you can’t find a way to reduce complexity talk to other developers as they might know of a way to reduce it. The more simple the software is, the faster new developers can start working with it and the easier the software can be extended and maintained.
Conclusion
I hope that I was able to show you simple things you can do to help external (and even internal) developers to understand an existing piece of software and to start development faster. That is not only useful for your own business, but will also keep the developers happy. Because in the end they are also just humans and get frustrated if they cannot make progress quickly. Of course there are more aspects that can be added, but in my opinion these ones are some of the most important ones.
