Who Are You Writing That Code For Anyway?

Special thanks to a number of people who reviewed this article and gave useful feedback and suggestions to me: Anya Roltsch, Frank Schubert, Olga Hollister, Ravi Varshney, Ashansu Pant, Marcus Blankenship, Sandra Jones, Taylor Davenport.

Writing code is a very personal act.

Software developers think about what they are going to write at work, in the car, at home, as they exercise, sometimes they even dream about the work they have to do or problems they need to solve.

The best software developers have an emotional connection to the code they write; they care deeply about writing software that is elegant, simple, and shows their competence as craftspeople and business domain experts.

Other developers, on the other hand, do not understand nor empathize with co-workers who analyze, read, work with, use, and troubleshoot the code they create.

In this article I will explain why developers should care about and think about the many different roles and people who will be affected as they write their code.

I will do this by describing the various roles on a software engineering team and then explaining what aspects of their work are affected by the code a developer writes.

The software engineering team

The general business world has realized that software engineering is as much a team activity as it is a technical profession. Software engineering teams made of collaborative, passionate, direct, honest people create significantly better software than dysfunctional teams or solo developers generally do.

Every developer on the team will have to read the code they create and maintain over and over as they enhance and troubleshoot the codebase together.  They will also have to understand every code pattern and abstraction used, which is especially stressful when a critical bug occurs or a large shift in thinking in the business requires a large shift in the concepts used in the code.

Your future self

My friend's daughter went to school and on one of the first days of the school year all of the kids were asked what their daddies do. She said "My daddy types text." Developers write code for many hours a day, sometimes every day.  

Writing so many hours a week can cause a developer to become lazy with their code patterns as they attempt to optimize time spent typing through terseness. The result can be unintelligible variable names, overly-optimized, hard to read code, overly broad exception handlers or exception handlers that ignore exceptions, lack of comments for parts of the code that are complex or critical to the businesses' needs, or poor consistency with coding style.

Get it out, get it done, move on until, sometime in the future - "we need to extend the blarg component to do Y." Silent scream! This code, who did this? I cannot make heads or tail of it! One run of "git blame" later and a face palm ensues - "oops, that was me?" 

Minimize the number of assumptions made in code about knowledge of business concepts and business logic. Make comments in the code about which areas of logic are exceptionally important to the business and why. Link to external resources that describe the products or services the code supports in the source code itself.

The QA engineer

QA ensures the styling and layout of an application's web pages look right on 4 different browsers on 3 different operating systems. They make sure application errors return meaningful messages to the application user. They intentionally attempt to misuse the application to verify that when the application code encounters unexpected input it does not crash and open the system up to stack pointer redirection attacks, remote code execution attacks, SQL injection attacks, or other security vulnerabilities.

Whether it is through manual testing or automation, QA does the work to make sure every release has a consistent user experience and level of quality.

A part of the QA team's job is finding bugs before customers find them; bugs often mean code halted before a specific business workflow completed. The exception may be intentional (rejecting invalid data from a user) or it may be that the server catches an unexpected, uncaught exception raised by the code and returns a generic error response to the user in their browser (e.g. an HTTP status code of 500), or a javascript exception is raised, generating a stack trace in the browser.

QA spends a lot of time thinking about code, exercising it, and troubleshooting it to make sure it looks like a fine diamond when customers see it.

Organize code logically, write meaningful, user-centric error messages, think about how a user might misunderstand business logic and pass the application unexpected input.

The on-call engineer

Hardware? CPUs? RAM? Network? Horizontal Scaling? Parallel processing? What is that?

Most developers have a pretty solid understanding of what all those terms are and an appreciation of the containers, virtual machines and hardware that run their code locally for development or in production where customer-facing applications are hosted.

Many developers do not think about the dark parts of that process - the failure of a program to start because a required configuration parameter is not present, the unexpected crashes when a compute resource runs short on RAM or disk space, the 2 AM in the morning (scream face) alert that wakes up the on-call person who then has to claw their way to a computer, log into one or more systems, do focused troubleshooting, root cause analysis, and break/fix work to correct a run-time error that has occurred.

Write meaningful log messages when important actions happen in a program, add useful context to error messages and make sure the error messages are understandable by the 2 AM human struggling to figure out why the transaction processor will not process transactions. Organize code thoughtfully so that even a non-coder has a chance to understand where things are happening and why.

The site reliability engineer / tier 3 engineer

Another group of people who generally do not look at code until things are at their worst: the system is crashing, invalid data is saved in the database, users cannot log in, the web interface intermittently shows a blank page or incoherent to end users system-generated error message.

These people care deeply about understanding the logic and layout of code so that when a run-time issue happens they can help the engineering team fix the error - by identifying where in the code the logic is failing, how many people the failure affects, and the severity of the failure. Failures can be unexpected program exits or performance issues - why is it that the application function that once only took 300ms now takes 10 seconds?!

When a business workflow error happens, raise an exception and create a meaningful log message that shows what happened and why. Name classes, functions, methods, and variables so that a person analyzing the code can understand the flow and functionality of it at the worst possible moment - when it is broken.

The software developer who recently joined the team

It is anxiety provoking being the newest developer on a team, especially if either the team is newly formed after a previous team was disbanded or the team is very mature and established in their code patterns and expectations.

Remember what is was like to be the new person? If you do not, take a minute to reflect - you had to figure out source code maintenance practices, coding standards, code organization standards, naming conventions, code patterns, and domain-specific terms used in the code and how they mapped to business terminology.

Minimize the amount of implied context and knowledge needed to understand the code. Use well-known and well-understood code patterns to organize code and the components that combined together form whole applications. Learn and follow the idioms prescribed by the community of developers who use the language the application is written in. Name variables using terms that are widely used and accepted in the business domain.

The entry-level software developer

What is harder than being the newest developer on the team? Being an entry-level developer! On top of learning team practices, you are learning how to design, develop and deliver code - many new mental models and practices to learn.

Entry-level developers are often asked to work on fixing bugs because bugs are focused tasks with clear goals and expose developers to many parts of a system. What is challenging about bugs as an entry-level developer? As an entry-level developer it can take significant time to read and understand code. There are many new business and software engineering terms to learn, many questions to ask to understand the code and find a fix for the bug.

Avoid jargon in variable, function, method and class names. Use simple patterns in code. Follow the principle of single responsibility. Help the entry-level developer on your team by writing code that is easy to read and understand.

The product manager

Product managers, product owners, project managers, Ui/UX staff, business analysts, scrum masters. Many roles involved in creating the business requirements, roadmaps, and context that an engineering team needs in order to create applications that brings value to the company. 

Think about the people who drive the need for software development at your company. Learn and use business domain specific concepts in the application to make the code and other components of an application map nicely to business-level terms and needs to make conversations with business people easier for them to understand.

The technical manager

That person. The one who ensures you get paid, the one who hopefully guides you, protects your focus and attention, helps you grow in your career, has empathy for your balance of work and home life, the person who wants to see you do your best and help keep you performing optimally through positive support, guidance, and a clear set of strategic and tactical goals.

Think about your manager as you write your code - be a craftsperson, make every line of code matter, spend sufficient time designing, asking questions, and discussing the hows of your implementation with your team before you write code.

Conclusion

There are many people within a software engineering team who use, care about, and rely on the code software developers write - have empathy, understanding, and appreciation for them and consider them as you create programs.

Who did I miss? What other roles or personas care about code? Who in your company, your team, your domain of expertise, cares about code that I did not talk about?

Now go forth and design and create applications with a deeper sense of empathy and understanding and respect for your profession, your peers, and the other professionals who work with you and the code your software engineering team creates and maintains.