How to criticize code

Dear new developer,

Criticizing code (and software solutions in general) is an important skill. It helps transmit norms, increase team knowledge, and improve solutions. But it isn’t something that comes naturally; at least, I had to learn how to do it. Similar to learning how to edit other’s essays, you must learn how to critique team member’s programming.

First, understand the context. There are two types that matter. The first is the business context. What problem is this system trying to solve? What limits does the business have (time, money, labor, understanding)?

In a startup, some of the code being written will be quick and dirty, because the startup is trying to find something that people will pay money for. Rapid exploration is more valuable than perfect architecture and maintainability.

You also need to understand the technical context. What is the scale/timeframe/level of the team’s knowledge? All of these things should inform your critique. I expect different things from an adhoc script in a data pipeline than I do from an embedded agent shipped to customers with little chance of future updates.

If you are part of a team, you may know these contexts, but they shift over time. So it’s always worth double checking before you begin a review to make sure you aren’t holding outdated assumptions. This can be as simple as a quick conversation with the author or team lead. It’s also helpful to regularly have these so that the entire team can be in the same mental space in terms of the engineering trade-offs they make daily.

Next, determine “which hill you want to die on”; that is, what is important enough for you to comment on. Which aspects of the code are important to you, based on personal experience, team goals, or ethical considerations? If you don’t know what the team values, ask! And then write it down so that others can benefit.

What you want to do with a review or critique is walk a line. You want to question and provide actionable feedback so that you and the author can improve the code and understanding of the system. But if you provide too much, the author may be overwhelmed or, worse, brush off your comments. You can ask what kind of feedback the author prefers; some folks have thicker skin than others.

Don’t focus on the small stuff. It feels like an easy win, but it really isn’t helpful. If you must give such feedback, preface it with “nit”. In fact, if you can automate away questions like spaces vs tabs or where curly braces go by using a linter that runs before a PR can be opened, all the better. Intent and high level feedback is where most of the value of code critiques lives.

Finally, a note on tone. You can be harsh with feedback, but don’t mix up someone’s implementation with who they are. They likely do that enough themselves; I know I sometimes get wrapped up in my code and take it personally when it is found wanting. The tone I find works best is one of assuming positive intent, but asking tough questions along the way. Trust that your team member has done the best they could, and try to focus on improving it and educating the both of you.

The end goal is to bring the code up to the current standards, or slightly beyond, of the codebase and team. Attacking anyone personally, even if they made a really ignorant implementation decision, actively undermines that goal in the future. I find that harsh feedback delivered in a kind tone is more effective than the reverse.



Think first about what problem this is solving and for whom

This is a guest post from Kate Catlin. Enjoy.

Dear new developer, 

Welcome to tech! Wow, I remember those days– Confusing, exciting, challenging. Nothing is certain except that you are in for a wild ride. Hold tight! 

The advice I’m writing to share with you today is this:

Before you write any code, think first about what problem this is solving and for whom.

As a little background, I’ve spent my whole career in tech. I’ve had two stints writing code (once in Android and once in Ruby) and neither lasted long. The rest of my career was a journey through Community Management, Sales, Startup Foundership, and now Product Management. While I love code, I love understanding people’s problems and figuring out how to solve those as well. That side always sucked me back in. 

Even in my roles where I wasn’t a developer, I’ve always interacted with developers. Many of them were new to the industry, just like you. The ones who have since excelled in their careers were the one who embodied the advice I just shared.

And so, every time you pick up a new Jira ticket or sit down to complete a new requirement, I suggest that you ask yourself the following questions: 

  • Who does this solve a problem for? 
  • What is the problem they’re trying to solve? 
  • How does this ticket solve it? 

There are three reasons this is going to help you out. 

First, it will keep you motivated. 

I think software development is one of the closest real-life professions to having superpowers. 

Why? Because your job is to use skills that most don’t have or understand in order to solve someone’s problem. 

Some of the problems you’ll solve may be big– Maybe you’ll work on an app that facilitates financing for renewable energy and measurably reduces climate change emissions. Some problems may be small– Imagine someone quarantining alone who misses their grandkids and has tried not to cry all day. Perhaps they have a slightly-less-frustrating time ordering a gift to send someone because you fixed a bug in a website’s UI. 

The world is a tough place to exist sometimes, especially in a pandemic. As a software developer, you get to use your powers to help make life a little easier for people. Remember that! Focusing on the problem rather than other things (like the shiny tech) will help you do so. 

Second, because you can start to push back if you see an easier way to solve that problem. 

A few months ago, I prioritized a new feature for CircleCI that would allow software developers, our users, to import Environment Variables from one project to another. I wrote up a long list of acceptance criteria involving multiple screens and checkboxes. 

The junior developer who picked up the Jira ticket for that feature was someone who regularly practiced user empathy. He paused, thought about it, and then suggested a simplified approach.

The simpler version worked! We were able to ship the feature in half the time, and it still resulted in a measurable lift to organizations adding new projects. This was good for the user, good for the developer, and good for the company. 

This is just one example of many I can name where by embracing user empathy, our team has solved more people’s problems faster. And so can you! 

Third, because it’s how you advance in an organization. 

Product thinking is so important at CircleCI, it’s a skill we specifically review our developers for during our annual review cycle. A minimum-threshold rating is necessary for a promotion. 

This is obviously not true of every organization, but in no case will the mindset not serve you well. Leaders simply need to understand why we’re building what we’re building for our users. How else could they help us achieve the future we’re working together to bring about? 

I would love to hear how a user-empathy mindset works for you. 

Everyone’s path is different, and every organization values different skills. You can find me on twitter at @Kate_Catlin, and I’d love to hear from you! 


Kate Catlin

Kate Catlin is Senior Product Manager of Growth at CircleCI.

Why and how to improve your writing skills as a software developer

This is a guest post from Allie Cooper. Enjoy.

It’s one thing to be able to write good code, but professional written communication is something else entirely. The ability to efficiently and authentically communicate using written language is an often ironically underrated skill in software development.

This is something that new developers need to get over very quickly. “Obsessions with patterns and algorithms don’t serve anyone’s mission by themselves,” explains engineer and career coach Minh Pham. “While coding might be your latest skill set, it is by no means an engineer’s only skillset. Remember that at the end of the day, it doesn’t matter if your code is ugly, fancy, verbose or concise – the value you create matters. Strive to be an excellent communicator, a quality teammate, and an outstanding human.” In today’s increasingly digitized workplace, achieving these qualities means honing your professional written communication skills.

Writing is Essential to Software Development

Any veteran developer can tell you that non coding-related writing is part and parcel of the daily grind, which includes writing tons of bug reports, notes for yourself, documentation for co-workers, and other technical discussions over chat or e-mail. You might also be tasked with explaining technicalities in ways that can be easily understood by clients. And as Inc points out, all of this generates a permanent record of any and all significant ideas, incidents, and other facts pertinent to how you’ve handled the job. In software development, the way you write and communicate over work platforms defines a great majority of your work history.

While writing code defines your raw ability as a software developer, your written professional correspondence tells the story of your ability to work with others in an inherently collaborative and complex field. Today, the sudden digital migration brought on by the global health crisis has only made professional writing a more integral skill for thriving in the new and increasingly web-based workplace. This is as true for experienced developers as it is for those who are looking to pick up the skills necessary for the job, which brings us to our next point.

The Future of Coding Education is Written and Online

From basic coding courses to advanced degree programs, more and more future developers are learning essential skills through online means. And the pandemic has only increased their numbers. For instance, Code Platoon Coding Bootcamp online basic coding courses have allowed the U.S. Department of Veteran Affairs to continue offering software development skills training for veterans as well as their spouses. And for safety reasons, all classes have been moved online.

Meanwhile top universities have also made this switch to training software specialists online. Maryville University’s online masters in software development is an advanced degree program that’s 100% web-based as well, with the perspective of producing future software consultants, UX designers, web developers, and DevOps engineers. And while these programs do include video conferencing classes, the majority of the work is through written communication. As natives to online work, the developers trained in these online programs are already developing the writing skills necessary to thriving amid the current digital migration.

In short, the field of software development is only getting more competitive and web-based. And while there’s no shortage of genius code writers for companies to cherry-pick from online universities and coding courses, the combination of a great coder and a great online communicator remains rare.

Practice Makes Perfect

Whether you’re already coding for a living or still learning the skill, you already have plenty of opportunities to hone your professional writing skills. Strive to be succinct and straightforward with every chat message or e-mail before hitting send. Put yourself in other people’s shoes – think about how the message you wrote will affect you if you were the one to receive it. Remember that every unnecessary word only muddles already complex conversations about technical specifications. Grammar is important, but so is writing with the perspective of being as empathic and as concise as possible – which can also allow you to develop a writing style that won’t require grammatical gymnastics. Never play to your emotions and always write with a collaborative mindset. The better you can communicate with the written word, the more value you can bring to any software development effort.

Allie Cooper is a freelance tech writer who specializes in I.T. and software development. Her mission is to help software developers further their careers. In her free time she plays online chess and sails.

Understand the use case

This is a guest post from Christie Brandao. Enjoy.

Dear new developer,

It’s easy to get wrapped up in only focusing on the deeply technical aspects of your job, especially if many parts of the stack have technologies you haven’t worked with yet. As your career progresses over time, you will be improving the quality and readability of the code you write as well as your problem-solving skills. This takes deliberate practice, but you’re already used to this! At the beginning, it’s natural for all your energy to go towards getting up to speed with the codebase and learning how everything works together. My advice is to take some time to also understand the use case.

At the core of it, your job is to be building something that will provide a positive business impact through your development skills. Ignore the urge to dive right in and start coding and instead, take some time to learn the bigger picture. Focus your energy on gathering as much information as you can to start building your foundational knowledge of this area of the product. You can start small! When asked to build upon a feature, for example, don’t just take the ticket at face value. Ask questions (to yourself or others) about how the current feature is currently working. What are the difficulties people are having using this feature? How is this going to be an improvement to the current process? Once you have a good grasp on the ticket level, it’s time to learn about the bigger forces that impact larger business decisions. You never know, maybe your fresh perspective will offer valuable insight that no one else has brought to the table.

— Christie

Christie Brandao is based in Columbus, Ohio. She is a Full Stack Serverless Web Developer for Branch, a tech-forward insurance startup focused on giving instant prices for home and auto with just a couple questions.