Since joining funda, Connor Christensen, Frontend Web Developer, is on a mission to inspire fellow developers to master Git. His rationale is simple: gaining a deeper understanding of its advanced features improves collaboration and prevents unnecessary code rewrites.
Using Git at funda
Approximately 90 per cent of developers worldwide are familiar with and utilize Git. Git is a vital piece of software we employ at funda to maintain a comprehensive record of our code's history and track changes. However, Git offers more than just version control; it serves as a documentation tool, allowing users to incorporate messages and organize their commits.
While many individuals possess a basic understanding of Git, I gave four company-wide presentations with the goal of inspiring fellow developers to invest additional effort into mastering Git's extensive capabilities.
See also: Why GitOps didn’t work for us as a company
Git competency is rather easy to achieve, and the benefits of mastery often appear to be outweighed by the difficulty of learning the most complicated aspects of Git. As with most technology, a little bit of guidance and a lot of practice can yield returns in subtle but important ways.
How we should use Git
Currently, Git is primarily utilized for tracking code history.
- As a way to save work
- As a way to collaborate with others
- If used masterfully, as a communication and documentation tool
Leveraging Git as a tool for documenting changes can provide invaluable information for future reference. This additional documentation streamlines issue resolution and, notably, should lower the amount of code that is re-written.
When confronted with intricate code, many engineers' initial reaction is to rewrite it if they don't comprehend the original purpose of the code. While rewriting may result in improvements in certain areas, it can lead to overlooking crucial aspects when the original intention is not fully understood. Software development follows a cycle of building and rebuilding, with the latter occurring unnecessarily when the reasoning behind the initial implementation remains unclear.
The problem lies in people forgetting their past work, and new team members lacking the ability to inquire about the reasoning behind previous decisions. Luckily, you can use a tool like Git to easily uncover the "why" behind specific constructions. This knowledge empowers individuals to make informed decisions more efficiently.
By using Git rebase to ensure linear commit history, authoring atomic Git commits, and using fixup commits to make the rebasing experience smoother, these advanced tools and practices support us in creating a history that is clear, concise and descriptive.
// When I wrote this, only God and I understood what I was doing
// Now, only God knows
The why
Maintaining such documentation can be challenging, as it requires discipline to consistently write quality code and descriptive commits. In my experience, few individuals prioritize this practice. Personally, it took me several years to develop effective documentation skills. Communication challenges are compound, as the business and business requirements scale. On a small enough scale, a one-developer project may not even need documentation.
However, as more people join the project, the need for documentation increases. With larger teams of 10 or even 100 individuals, it becomes even more difficult. At a certain point, documentation becomes just as important as the code. It's not just about understanding Git; you must also learn how to communicate effectively in this context.
Six essential questions
Understanding the reasons behind code changes is crucial during development, and documentation plays a vital role in achieving this. When documenting, it is essential to address the six basic questions: what, where, when, who, why, and how. These questions facilitate effective communication by providing most, if not all, of the necessary context.
However, enforcing good documentation can be challenging, as it is not a mandatory step for code execution. Technically, once the code is functioning, the job is done. But if a new person comes along, they will inevitably fix something and break something else.
Communication is hard. But if your commit contains the answers to all six basic questions, then you’re doing a good job. Even if the communication is not perfect and the answers may not be ideal, it is always better than no documentation at all.
Code rewrites
Regrettably, it has become an industry standard in the web world to rewrite code every two or three years, which seems unreasonable to me. I firmly believe it doesn't have to be this way. There are companies that successfully avoid total code rewrites altogether, but it requires a significant amount of discipline to meticulously document everything and maintain code integrity over time.
While there are instances where rewriting code is justified, it is unacceptable for complete rewrites to be the prevailing norm. Many people view it as an inevitable cost of doing business, but this ultimately comes down to a lack of testing, documentation, and effective communication. All these factors contribute to the need for code rewriting. Learning these essential skills is indeed challenging, but acquiring and honing them can serve as a preventive measure against unnecessary code rewrites.
Mission
Since joining funda, I have witnessed significant changes within the team around recognising the benefits of documentation in Git. It is common for individuals to overlook the advantages until they experience them. It often requires someone to demonstrate the value, and that is precisely what I have been advocating since I joined.
My advice to everyone is to try and incorporate advanced git tools in your workflow and always ask yourself if each commit appropriately conveys 'what, why, and how'. Once these new tools become comfortable, you can assess how they can best improve the workflow for you and your team.
If you're interested in learning more about this topic, here are a few helpful resources to expand your knowledge.
See also from funda: An engineer's relocation journey to join funda
