Writing Agreeable Code

Reflecting back on my career so far, there are some bits of advice I wish I could tell my younger self (like to take a course on compilers 😄). One of them that I’ve been mulling over recently is more about social dynamics of how we write code within a team and how the code we write is as much of an interaction as a conversation. I’m sure this advice isn’t new but I have yet to find it wrapped up together like I hope to do here.

Don’t Break Standards

Often when joining a new company, team, or project; we bring a lot of technical baggage with us. The languages we prefer, the frameworks we are comfortable with, the coding-style we like most. If you’re coming into a greenfield project, then you should definitely lay out your opinions and argue for them as your team defines it’s standards. But, if you are joining a new team then you should adhere to their standards.

Is the standard non-idiomatic? Have languages been chosen you believe to be sub-optimal? As long as the team is achieving its goals and the rest of the team is in agreement with the standards, you should follow them.

Does this mean you can’t propose changes? No. Of course standards are always in flux, but be considerate. When proposing changes, ensure not to insult the team’s previous choices. Hostility toward existing standards will likely not win you any supporters. Also, it’s important that you believe that any changes to the standard you propose will have a positive impact to the team’s goals/objectives. If you’re proposals don’t care true value other than “being the right way,” then you are wasting your team’s time and resources.

Don’t Break Patterns

Every application, through it’s development and growth, develops it’s own patterns. They become the basis for how change is introduced and how future development is done. Always do your best to follow these patterns.

Patterns are a form of communication. When we deviate from existing patterns, we are speaking a foreign language than the rest of the code. While contributing new patterns is a natural evolution, individual “snowflakes” are like ancient Greek in the middle of a modern-day novel. They make no sense; they are confusing; and can be frustrating if forced to read, understand, or change.

Don’t Nit

I’m guilty of this from time to time, as I think most of us are. A nit, or nitpick, is small comment when looking at someone else’s code, doing a code review, etc. Usually along the lines of “fix indentation here” or “you started your { on the wrong line.”

Nits are distracting to meaningful code-reviews and can come across as insulting. Nits not only come across as overly-critical, but also be seen as wasting time with small fixes that do not functionally change the code. Most of all, nits should never exist in the first place. Automated formatters and linters should be employed, along with build-systems to enforce, so that developers can automate the small details and focus efforts, both during writing and reviewing, on meaningful contributions.

Always Write Documentation

Writing code should always be seen as a way of communicating. This means that we should strive to write clear and concise code; prefer easy to read code over “clever” solutions. But often, for sufficiently complex or sufficiently large portions of code, that is not enough.

Writing documentation ensures that everyone has a shared understanding of how the code works, or at least how it should work. This not only saves a lot of time when discussing changes within a group, but also eliminates some contentious moments where opinions differ because there is not a shared understanding.

I should mention that this goes for both new code that you are writing as well as old code that you’ve taken the time to understand. Documentation is a way of contributing knowledge to your immediate programming community and is a kind thing to do and we all enjoy random acts of kindness, right? 😃

Always Write Tests

When venturing into the unknown or not-well-known, disagreements can arise as to what a particular bit of code should. Whether it be an undocumented library function or an advanced language feature, it is important that the code does what you expect.

Tension here can arise in code-reviews when the reviewer may not share the same opinion of what the code is doing. By writing tests, we are able to prove to others within our group that the code does match any assumptions made. There are many reasons to write tests, this is just one more you can add to your list.

Always Have Buy-In

Remember to be humble. You don’t have all the answers, and you don’t have to.

When making changes that will affect a number of people/teams/systems, it is important to have buy-in. That is, you need to discuss your proposed change (this means before you start coding) and get approval from everyone affected.

The reason is to ensure that you aren’t forgetting a use-case that will either be broken with your change or a use-case that is not fully addressed by the change. Buy-in really just means validating our current spec (because we all right specs for our changes… right? 😅). Of course, this can slow you down when you will run across those who disagree with your changes. However this isn’t a bad thing, this may just mean that you do not have a shared understanding of the system.

Any time you encounter a co-worker that does not share your view of the world (as it relates to your code/software), it is important to discuss. It either means you have a gap in your knowledge (or perspective), or they do. Either way, it is good to discuss and get everyone on the same page.

Why?

As software developers, we should be striving to make an impact. To make a difference in the success of the projects we work on. Writing agreeable code ensures that we meet as little resistance as possible, meaning more time for real work; more time for meaningful contributions.

It’s also important to remember that we do not write code in silos. We are part of a community, whether it be your team, your company, or open source. The code we write is an expression of ourselves and a form of communication. Agreeable code is a way of engaging in healthy dialogue within your community. It breaks down barriers, builds trust, and fosters kindness. It’s important that we support and foster our community and agreeable code is one way in which we achieve that goal.

I hope you’ve enjoyed this article and please leave any comments if you’d like to continue discussing. You can keep up to date on the latest posts by following me, John Murray, on Medium and please 👏 if you enjoyed the post.

Writing Agreeable Code was originally published in Hacker Noon on Medium, where people are continuing the conversation by highlighting and responding to this story.