Often when joining a new job, you won’t be writing a new codebase from the ground up. Often we’ll have to familiarize ourselves with the preexisting codebase. Sometimes this codebase is old and needs to be updated or refactored. But how should we go about doing this? It is challenging enough to try to learn a new codebase, let alone trying to change or add to it. That’s what the question the article “Reducing The Learning Curve For Supporting Aging Codebases” by Scott Fitzpatrick aims to answer. The articles offer some dos and don’ts when it comes to trying to make it easier to learn a code base.
One of the first don’ts is to not rely on face-to face conversations and messages/email conversations. While these conversations can be helpful for developers in the moment, they offer little for someone trying to learn the codebase. Plus they can be hard to find and subject to deletion. I think the main point to take away from this article is the importance of good documentation and other resources. When it comes to making a codebase easier to understand, not just for newcomers. Having multiple avenues to try to learn from is important. Beyond just looking at the code, things like data flow and entity-relationship graphs.
Other aspects beyond code are important too. Like good documentation on local environment set-up and system requirements/dependencies. Making these clear not only makes it easier from the newcomer, but also it helps learn about the frameworks and why they were chosen for the project. Knowing why an application uses certain frameworks and projects can help a new developer understand the reasoning and choices of the team.
Learning a new codebase is very challenging for anyone. I think this article offers good insights as to why certain practices are good and why some are bad. This also once again highlights why I think communication is the most important skill for a software developer. Being able to communicate with other developers not only through code, but through documentation is a very important skill. Making the lives of fellow developers easier by finding as many ways to communicate design and ideas. Although most developers hate writing documentation, it is a necessary evil that must be done.
I will definitely keep this in mind when writing code. Of course writing code that is readable takes precedence. But keeping up to date documentation is also vital to keep projects on track. I personally haven’t worked on a large project involving a large codebase before. So I haven’t had to write documentation for something that I didn’t write. Most of the time I don’t feel the need to write what the function or class does because I made it, so I already know. I think that’s a habit a lot of programmers have, that leads to a lot of lack or bad documentation. It’s something that I don’t have a lot of practice in, so its a skill I’ll have to start honing.
From the blog CS@Worcester – Code Craft by Kyle Tucker and used with permission of the author. All other rights reserved by the author.
