Repository Management - Maintaining Code and Developers
Preamble: Some of the contexts and terms used in this
article are from the stand point of a team of developers, working in an Agile
environment. Some of the developers are remote working. The team uses Source
Control Management (SCM) to maintain their codebase.
Good repository management is not only about the maintenance of code; it’s about knowing who is doing what. At the heart, a source control system is based on code commits. Commits are the progressive steps in the development of software. These commits not only advance the code, but keep a track of comments made by the developers who make the code changes.
These comments can and should be of great interest to a development team. Imagine a scenario where you have a project management board which lists each developer, which ticket they are working on, and the latest commit they made on the code. If the messages are informative, this could be a great resource. A team lead could review this board on a regular basis during the day and use it to assign resources accordingly, perhaps when they see a developer having an issue, and know that another developer was working on something similar.
This leads us to a potential roadblock: are the comments good enough for another developer/team lead to understand any issues, and do the comments exist at all?
When working for a team that does not have a strict policy on using source control, this roadblock is immediately apparent. Developers in these teams tend to have very different ways of doing things, where source code is concerned, and that’s an issue that is both easily addressed and beneficial to the team.
You may have developers who work off the main branch, keeping
it up-to-date with the remote main branch, and only create the ticket branch at
the end of coding, when it is ready to go to QA. The problem here is that if
they are working of the main branch, it is highly unlikely they can make
commits against it, and therefore no commit messages. In this case, they will
have a single commit message when they push their ticket branch to the remote
repository. Going by the notion that commits are what progresses the code, it
would seem as though the developer picked up the ticket, wrote the code in a
single sitting, and then pushed it to the upstream. For small bugs this may
well be likely, but for continued software development this is highly unlikely.
Other developers will create their code branch from the main branch, but then will not make any commits to it, and will simply continue to work on it until the work is complete. This again has some major problems, when working in a team.
If commits are not made regularly, you have no way to track the progress of a piece of code.
Let’s look at a very probable example, to highlight an obvious flaw:
Developer “X”, who works remotely, is tasked with adding a new interface to an area of code, let’s say to allow some user input. This new interface was not realized in the scoping of the epic, and so is needed quite urgently. Let’s say that turnaround is 2 days.
Developer “X” updates their local master branch and begins
coding. Developer “X” has not created a new branch. At the end of the day,
Developer “X” logs off their machine and goes about their evening. The next
morning Developer “X” wakes up, late, and realizes that the power is out in
their neighborhood. While the power company is at fault here, this is something
that happens all the time and so is a highly probably situation. Developer “X”
calls their team lead and explains the situation. The team lead understands
that these things happen and will get Developer “Y” to complete the ticket.
Developer “Y” looks at the reference number for the ticket and then looks for a remote branch with the code from Developer “X” …but one does not exist. Developer “Y” calls Developer “X” and discovers the issue…the code was never committed or pushed. Developer “Y” now has 1 day to create the code needed for the ticket.
In situations like this, Developer “Y” may well end up omitting part of the interface after discussion with the project manager, or may cut corners to finish the code. Either way, the task is incomplete.
This could have been resolved by Developer “X” creating a branch off the main branch, and committing and pushing the code at the end of the day. Developer “Y” could then have picked up and completed the task.
But is this enough? Let’s look at another all-too-common situation to highlight another flaw in not having SCM standards.
Developer “Y” was asked to create a new feature for an existing piece of software. While this is a new feature, it is not a new concept. Developer “Y” updates their local master branch from the remote master branch, creates a new branch off that using the ticket reference number, and begins to code.
Developer “Y” comes across a problem in developing the feature that will need some trial and error to solve. While there may be some complex solutions to the issue, Developer “Y” is very aware of the need for the code to be performant, and so decides to spend some time looking at possible solutions.
Several days before a software release is due, the project manager gets all the developers together for a “Go/No Go” meeting. At this meeting, Developer “Y” states that their feature is a “No Go” due to having spent some time developing a solution to a problem they encountered. Developer “Y” then lays out what the issue what and what they did to resolve it, and why it took longer than expected. At this point Developer “X” states that they had a similar issue a while back and solved it by adding a new method is a certain code-class, which Developer “Y” was not aware of. Because this issue had happened before, the team lead was fully aware of the problem and solution, and had they known that Developer “Y” was having this issue, could have assigned Developer “X” to help with it, in which case the release would have been a “Go” across the board.
While these issues sound trivial, they happen all the time and hold up software release cycles. Good and regular code commits and pushes would solve these issues, and many more like them.
Think about code commits as conversations: you are making everyone else involved aware of what you are doing. A god comment on a code commit can help in those situations when you look back on your code and ask “Why did I do it that way?”
Code commits should be organic. They should not happen at set intervals during the day, or only at the end of it. They should happen when there is a natural break in the development cycle; when a problem has been solved, or when switching context. This leads naturally to a more modular development process, where it is easy to go back and make changes. Good comments in code commits can be analyzed and acted upon, leading to better overall architecture and design, better project management and added team awareness. And all this at the cost of a few seconds.