How to Onboard Software Engineers – Interview with Kate Heddleston

In this interview with Kate Heddleston, an independent Product Engineer, we discuss technical onboarding. We cover why onboarding is important, the essential elements to effectively onboard engineers, the areas you should focus on, who should do it, as well as common mistakes,  made. Kate writes about technical onboarding, training and mentoring on her blog.

Introduction
Derrick:
Kate Heddleston is an independent software engineer in San Francisco. She volunteers at Raphael House and is mentoring with PyLadies and previously at the Hackbright Academy. She also speaks at conferences about a range of software engineering topics including technical onboarding, training and mentoring. Kate, thank you so much for joining us today. Do you have a bit to share about yourself?

Kate:
I’m a self-described product engineer, which means I like to build features for people, but I keep building infrastructure tools because I decide that I absolutely have to have something in order to build my websites. I talk about web application development and web application infrastructure.

Derrick:
With your experience with onboarding specifically, what led you to start talking about it?

Kate:
I noticed that there was this discrepancy in the career trajectories of men and women at startups that I was working at. I was trying to figure out why because the people coming in were of the same experience level, which is out of college, so pretty much none, but the guys over and over again would get promoted faster and get to the next level faster. That is a whole separate topic of conversation, but the big thing I noticed first was that without onboarding, women were left behind more than men. I was really confused by that. I was like, “Why is that women are hurt more by a lack of onboarding than the men?” That’s what led me to start researching and putting together my talk.

“There are 2 ways to get great engineers at your company. You can steal them or you can make them.”

The Benefits of Onboarding
Derrick:
With onboarding, if done well, what are some of the benefits?

Kate:
Basically the way I think of it is we spend a huge amount of money recruiting and sourcing engineers. We pay them huge sums of money to work for companies, and we bring them in on the first day and then we’re just like, “Whatever. I’m sure you’ll be fine in our massively complicated website that is developed and maintained by many, many people. You’ll figure it out.” We’re under-utilizing people, which is expensive for companies and people are unhappy when they aren’t fulfilling their potential. That can lead to attrition. It’s one of those things where once I saw it, I was like, “This is so incredibly obvious that companies should have onboarding.” The return on investment is incredible. It benefits everyone. I came to it from a place of, “Why are women being left behind?”, but at the end of the day, onboarding is really for all humans. It’s one of those things where you get so much more out of employees who are happy and productive and feel integrated into the team, so why wouldn’t you do it?

Getting Started with Onboarding
Derrick:
Who within an organization should be involved in onboarding?

Kate:
Pretty much everyone. ‘It takes a village to raise a child’ kind of thing. The common first approach to onboarding is to place new employees with really senior mentors, but mentoring is actually really hard. It’s a lot like teaching in the sense that it’s very emotionally draining. What happens is … This is experience when companies hire a lot of junior engineers. What happens is they burn out all their senior mentors. They get tired because teaching is hard, and they’re like, “We can’t take on any more junior engineers. We can’t take on a lot of new engineers who aren’t really senior.” If you spread out the load, so if instead of pairing every junior who comes in with a super senior engineer, you pair them with the last people who joined, like sophomore engineers, how they do sports in high school and college, you can start to spread out the load because the best person to teach something is usually the last person who did it.

The best person to help someone set up their development environment is the last person who joined, regardless of seniority. The best person to teach someone about a particular part of the product is the last person who developed on it. That way you can spread out who is helping who so you don’t burn out people emotionally. In fact, really senior people are not necessarily that great at teaching junior people. They’ve forgotten what it was like to learn things for the first time so it can be really painful. It’s nice to have the intermediate people turning around and teaching because they grow a lot.

Derrick:
Do you just start onboarding a new employee from their first day on the job?

Kate:
The way we’ve recommended setting up onboarding plans is setting up goals and then making them happen. For a lot of companies, if they have good enough infrastructure, being able to ship something on the first day is a really good goal. This new engineer comes onboard and in their first day, they actually push something to production. Even if it’s just a small bug fix or I don’t know, some config files that you might need for something, it’s a really nice thing to feel like you can contribute on your first day, especially as a software engineer. Setting up goals like that and setting up goals for when people are able to manage their own projects or work independently, the thing I say, the goal with onboarding is what I call reliable independence. Someone is able to reliably and independently build software on your team. For someone who is really senior, that might take 2 weeks, which is awesome. For someone really junior, that might take more like 6 months.

Derrick:
What steps or first things do people need to do when implementing employee onboarding?

Kate:
There’s no real good literature out there on exactly how to set up an onboarding plan. It varies hugely depending on the size of the company and the quality of their internal tools. I’ve talked to companies where we’ve sat down and the first thing I’ve said is, “You actually need to dedicate probably 2 or 3 engineers to building internal tooling because if everyone has to come in and manually set up everything, what you have is this super painful onboarding process that’s just going to bottleneck your company.” One of the first things, I think as an engineer, that you should do is automate things. Automation is great. People should be able to get set up really easily with their development environment. They shouldn’t spend a lot of time having to do all these installations that you do once that have no learning value. That’s the first thing I think companies should do.

The second thing is put together a Trello board and come up with some goals of what you want to see. You can section it basically by the rough seniority level of someone coming in: senior, mid-level, junior. Just knowing that someone who is junior is going to need a little bit more hands-on attention and someone who is senior is probably going to want freedom earlier. Then just set up goals of what you want to see them doing in the first day, the first week, the first month. I know a lot of people at companies who care a lot about this are often newer employees who went through bad onboarding and junior employees who went through bad onboarding. I think one of the big things for companies that I recommend is executive level signoff because there’s nothing worse at a company than fighting a Director of Engineering who is like, “Do we really need onboarding?” You’re like, “Yes, yes, we do.”

Derrick:
Beyond those first things, what else can you try?

Kate:
There are 3 major categories that people need to develop in in order to become reliably independent. They’re each about a third of what someone needs to know. We focus a lot on technical knowledge. Everyone is like, “Getting someone onboard is about teaching them about Python or whatever technologies we use.” I say that’s only about a third of what they need to know to be an engineer at your company. Another third is company structure, the internal tools that you have, the way that you build, the way that your code is set up. That’s another third of the knowledge that somebody needs. It’s basically domain specific engineering knowledge which is huge at companies.

Another third is personal development, things like confidence, the ability to research problems, the ability to debug independently, a judgment which is huge. Probably the single most important thing in most engineers is judgment. That’s another third of what people need to develop. I think focusing on each of those areas is really good. People are going to come in stronger in different categories. Everyone is going to come in not knowing that much about your internal company structure, but some people might have more confidence, more debugging skills. Some people might know a lot more about the technologies that you use. Just filling in the gaps in the areas that they aren’t as strong in.

“If you can’t hire any junior engineers… into your organization, you have serious problems”

Creating the Best Environment for Onboarding Junior Developers
Derrick:
Is there anything else somebody could do to create a great experience for junior engineers in onboarding?

Kate:
Recognizing a few things about the beginners is very important. First pairing them with someone who is one level above is actually most effective. Second, one of the tenets of expertise is the ability to recognize boundaries and scope really well. One of the tenets of being a beginner is that you cannot recognize boundaries and you are unable to scope problems and scope your world. Expecting a junior engineer to be really good at scoping a feature is unrealistic. That’s one of the skills that they have to learn. Whatever you give them to do, just scope it. Then let them go play. Give them a feature that’s really well defined, that has a clear area where they’re working on and then let them go and fumble around with it. I always tell beginners, “If you come across an issue, research it for an hour and then come talk to me.” It’s not to be mean. I’m happy to answer questions. It’s just that learning to research something on your own is really valuable and figuring out things on your own is also really valuable.

The final thing for junior engineers and beginners, in general, is helping to bolster confidence. Some people do come in and they have an overabundance of confidence, but there’s a lot of people who come in who are very insecure. People think that confidence follows skills, but it’s usually the other way around where skills follow confidence. If someone feels good about what they’re doing, they’re more likely to explore it and ask questions and to believe that they’re able to solve the problem.

Derrick:
You’re a proponent of weekly 1-on-1s, including 1-on-1s with anyone in the company, why do you think that they’re so important?

Kate:
I think talking to other people is really valuable. There’s a whole industry where you can pay to go talk to someone for an hour every week about your problems. I think people need to be heard. I also think that a huge part of what managers should be doing is listening. It forces managers to listen, hopefully, and it gives people an outlet to talk about things. I also think that you should have channels of communication that are open at all times. One of the arguments I hear against 1-on-1s is that very often engineers will come in and they’re like, “Everything is great. I’m fine. I’m super happy.”

I’m like, “That’s awesome. That is so great that your employees are really happy, but if something bad happens, they’re not going to want to have to schedule an emergency meeting with you. You should have open channels of communication so that they can come to you at any time and be like, ‘You know what? Something happened. Things are not good this week. I am unhappy about something.’” Having a constant rapport makes it easier for them to come to you in bad times, which is really what you want. The communication channels and 1-on-1s and things like that are just to set up relationships so that people feel comfortable coming to you with bad news, which is actually a very difficult thing to do.

“I always tell beginners, ‘If you come across an issue, research it for an hour and then come talk to me.’”

Common Onboarding Mistakes
Derrick:
When organizations are onboarding, what are some common mistakes you’ve seen?

Kate:
The big ones are burning out senior mentors. Then that leads to, “We can’t take on any more junior engineers,” which is a huge travesty. When I hear companies saying that “We only hire senior engineers,” I’m like, “Who do you think is training all of these senior engineers? Where do you think they come from?” There are 2 ways to get great engineers at your company. You can steal them or you can make them. In this day and age, you’d probably better have outlets for both. You should have a sustainable program of bringing on junior engineers. Depending on the size of your team, sure, you might only be able to handle a few at a time. Totally fair, but if you can’t hire any junior engineers if you cannot hire any beginners into your organization, you have serious problems with your team structure and your internal tools probably and basically everything that has to do with bringing someone new onboard.

Let’s see, other common mistakes … Bad internal tooling. This is the whole infrastructure thing that I get on. Having a really good infrastructure means not only can you deploy code quickly and reliably, which is what a lot of people talk about, but it means that you can also bring new people onboard. If you have a really easy to use a robust system for testing all of your code and deploying it, that is much, much easier for someone new to learn. It’s also a great system for people who are beginners. It’s robust. It’s easy to use. We can train a junior engineer to deploy code. Some of the best things I’ve seen for web applications are 1-click deploys, being able to deploy code to any service with the click of a button is great. Similarly 1-click rollbacks, really good, integration testing and things like that.

Derrick:
Kate, thank you so much for joining us today.

Kate:
Thank you so much for having me.

We’re Bad at Interviewing Developers (and How to Fix It) – Interview with Kerri Miller

In this interview with Kerri Miller, Lead Software Engineer at LivingSocial, we discuss how to hire and interview developers. We typically don’t get trained on interviewing and we’ve all experienced the haphazard approaches of those new to it – poor organization, repeated questions, fizz-buzz… Kerri tells us how to run interview days, the types of questions to ask, how else we can evaluate candidates and what to do after the interview. For more tips, Kerri writes about software development and hiring on her blog.

Introduction

Derrick:
Kerri Miller is a lead software engineer at LivingSocial. She is also a RailsBridge instructor and frequent conference speaker. She talks about software development and hiring, including the talk, ‘We’re Bad at Interviewing and How to Fix It’. Kerri, thank you so much for taking the time to join us today. Do you have a bit more to share about yourself?

Kerri:
I am actually, in fact, a lead software engineer at LivingSocial. Part of that is working with junior developers, or more junior developers, leading software teams and projects, and I also do a fair bit of work in our engineering culture team, so doing things like how do we propagate a good culture for code reviews, post-mortems, and hiring.

“You want them leaving the interview process regretful that they didn’t get hired, not resentful that they didn’t get hired”

What’s Broken with Developer Hiring?
Derrick:
What do you think is broken with the current way a lot of companies hire and interview?

Kerri:
We don’t do a really good job of hiring with intent. We decide that we need more people, but we don’t do a really good job of figuring out what we need those people to actually do, and who we actually need to hire. I like to think of my software teams as little ecosystems, little, tiny arcologies that exist in a bottle. They’re not entirely a closed environment, and, like any ecosystem, anytime you introduce anything new to that realm, there will be changes. There will be impacts.

Any time you hire somebody, you’re changing that ecosystem. You’re introducing a new species or a new variable to things and it’s going to change. Thinking about what you want to change means that you have to have laid that groundwork to understand where you are at the moment. A lot of teams and companies don’t do a really great job of understanding that. They’re just simply, “We need more bodies. Let’s hire bodies.” They don’t go into these things with a conscious sense of where they are and what they need, and how the future’s going to change by adding more people.

How to Structure and Run Interview Day
Derrick:
Let’s talk about the interview day. How should we structure it, and what are some key aspects you need to get right?

Kerri:
You need to go into it having a plan, and that plan starts with knowing what questions you’re going to ask and why. Understanding that every question you ask that a candidate can’t answer, or every step of that process is an opportunity for a candidate to filter themselves out of that process, it’s a point for you to get information to make that final decision. I think it’s really important that you take a look at what that plan is going to be. If you have, say, three people, and you’re hiring for a front-end developer, you should have one person ask about JavaScript. You should have one person ask about, perhaps, browser interaction, or working with designers, or what have you. Just splitting up that interview so that you’re not asking the same questions over and over again, you’re really able to get really solid signal on a person’s skill sets, what they’re comfortable with, and what their concerns are. What kinds of decisions are they making?

Good Types of Questions
Derrick:
What are good kinds of questions that we should be asking?

Kerri:
Well, I’m not a big fan of whiteboarding, because I think that’s something that we just automatically do, and we don’t think about, “Well, what questions are we trying to answer by asking a candidate to solve a problem?” Are we dinging people for trivia questions, for not remembering, “Oh, I need this third option flag or an obscure method from a core library.” Instead, I really want to focus on questions that are asking about decisions that they’ve made, what choices have they made, and what choices would they make again in the future? Are they reflective about mistakes that they’ve made? Are candidates looking for opportunities to improve, and how do they actually go about it? Do they make plans for themselves, like how they would improve a certain skill set, whether that be a technical skill set or a more soft skill set, for example, management, or project shepherding for example. Those are the kinds of questions that I think really get you at the heart of not necessarily what somebody knows, but what they’re capable of.

Beyond the Interview – How Else to Evaluate Developers
Derrick:
You’re a proponent of evaluating candidates in other ways than just an interview. How else should we be finding out more about potential employees?

Kerri:
I’m a really big fan of pairing on projects, like actually working with somebody. It doesn’t have to be a formal or traditional pair programming situation with one computer and two people, talking through the technical choices that they would be making as they programmed on something. At LivingSocial, we do a code challenge like a lot of companies do, using that as, then, a launching pad to have a discussion with a candidate to say, “You solved the problem using this technique. Why didn’t you choose this other technique? Why did you choose this one? How would you do it better? What if we sat down and refactored?” That’s one really good way to really get the heart of why are they making the decisions they’ve made? Not just did they make this choice because they didn’t know, or are ignorant, or did they make this choice because they had a certain belief about what the requirements of a given project were? That’s one way to do it.

Other ways you can be finding out more about potential employees … I’m a really big fan of asking the employee to explain something to me or teach something to me. In the past, we’ve done this with simply just saying, “You can teach me anything, something that I don’t know, and preferably is non-technical.” How well do they communicate about something that they’re a local expert in but they’re intended audience is not? Could they then go off and go and learn a new framework, or go have a meeting with, perhaps, a stakeholder, or a client, and come back and explain what the actual requirements are to me, to distil down what I need to know and communicate that well? Communication is such a big part of what we do in this job, and so testing for that essential skill in a really clear and explicit way can be really useful and get you a really good signal about who that candidate is and how they’re going to fit into your organization.

“We don’t do a really good job of hiring with intent”

After the Interview – Making the Hiring Decision
Derrick:
After the interview, what are key things that employers should be doing?

Kerri:
I think it’s really important that we don’t just say, “We’re going to get back to you,” but to say, “We will get back to you by Thursday, end of the day.” Then, if you can’t make your decision within those three or four days, communicating that to the candidate so they have expectations that you can meet, because it’s not just good for the candidate, it’s good for you as a company to have that discipline, because you want people to, whether you hire someone or not, you want them leaving the interview process regretful that they didn’t get hired, not resentful that they didn’t get hired. Being professional and upfront and just friendly and encouraging about the entire process is great.

I try always to make sure that, if we can’t hire somebody for whatever reason, we make sure that we give them constructive advice or feedback afterwards, or at least make that available. If you did like somebody, if it came down to either Joe or Mary, and you hire one or the other, keep that person on file, and follow up with them in a few months to see how are they doing, what’s going on? “Hey, we have an open position, would you like to re-apply, or would you like us to consider you for that?” That gets into the part of how you keep metrics on things as well because if you didn’t hire somebody, figure out why you didn’t hire them and then follow up and see, are they actually doing that work, and did we hire the … Not necessarily the wrong person, but did our process let us down? If you assume that somebody didn’t know anything about, say, SQL, and now they’ve gone on to work on a SQL-heavy project, for example, what in our process missed that step?

“It’s really hard to look at who you hire and decide that you have a good or bad process. But you can look at who you don’t hire.”

Derrick:
Great, so we talked about having a plan as part of the hiring process, what’s a good process to follow to make a hiring decision?

Kerri:
When you split up the interview topics, the questions you’re going to ask, and you’re going to consistently ask all of your candidates, it feels a little bit like reading a script, but it really lets you compare apples to apples as much as possible. Once you’re done with your little section of the interview, you should immediately go back to your desk and not get back to work but write down what your impressions were. What were the pros and cons, the bullet points, and find something good about the candidate and something not-so-good about the candidate, something that you wish they did have? Doing that at that moment and passing that back to a central person so as not to … Don’t pass it back to a group, pass it back to a central person, whether that be an HR or the hiring manager, to collect that, so you’re not coloring the impressions of other people.

When you get back into that room with everybody else, whether it’s virtual or real, to really discuss your opinions, you’ve got your opinions of the moment and you can’t be swayed by the impressions of somebody else. For example, if you were supposed to interview them about JavaScript, and the senior JavaScript person, who’s got twenty years of experience in JavaScript, just really did not like that person, how would that color your opinion if you had to give your opinion in that moment? If you wrote it down previously, no, this person really is good at JavaScript, then you’ve captured that honestly and you can really give honest feedback about what that person’s qualities are and what their strengths are without being colored by other people in that discussion.

Measuring and Improving Your Hiring
Derrick:
You hinted at this earlier, but a key part of your approach to hiring is measuring the process to improve it. How could we go about measuring the effectiveness of our hiring?

Kerri:
It’s very seldom that we ever hire anybody bad. When you hear horror stories about hiring, it’s always somebody else’s team that hired that one jerk, or that one idiot, so it’s really hard to quantify because now we know that person, and we’ve worked with them, and we understand their strengths and their weaknesses. It’s really hard to look at who you hire and decide that you have a good or bad process. You can look at who you don’t hire. You can look at that in terms of what were the false negatives? Did we bounce this person out of the process for a specific reason and then it turns out that that reason wasn’t good based on where they ended up going to work?

It’s really easy to LinkedIn stalk people, and peak into their GitHub profiles if they’re doing that sort of work, to see what they’re doing a few months later. It can be really useful to, four, or five, six months down the road, go back and look at the candidates that you passed over and see what they’re doing to understand, if you keep records of the questions that you ask, and the reasons why you maybe didn’t hire somebody, to see if those reasons are still valid.

Other metrics that I think are really, really important to an organization are understanding what your pipeline for candidates consists of. At each step, you have a certain amount of leakage, because people just simply don’t make it through the process or they abandon the process, they disappear. How many people are you losing at each step, and is there one step that you’re losing a lot of people at? Maybe you need to refine that step, remove it, or move it earlier or later in the process based on what your organizational needs are. I think it’s also important to look at who you’re losing as well. Are you losing junior developers at a step that you really don’t want to be losing them at? Are you losing more diverse candidates? Are more women abandoning your process at a certain step than men are, and understanding, or questioning at least, your process to see, is that a problem? Can we fix it? How do we fix it?

“You should immediately go back to your desk, and not get back to work, but write down what your impressions were”

Common Developer Hiring Mistakes
Derrick:
What are some common mistakes you see companies making when hiring developers?

Kerri:
Some of the more common mistakes are hiring from our friend networks. I think that the friend network is such an important part of how we get jobs, but it also tends to reinforce our monocultures a little bit. We tend to be friends with people who are mostly like us, and so those are the people that we’re going to be recommending, and so those are the ones that get hired more often. When I was mentioning earlier how the team is an ecosystem, it’s important to have some diversity there, and not just the diversity we talk about in terms of gender or ethnicity or race, but age, class, looking at people’s technical backgrounds, do they come out of CS programs versus being a self-taught or a boot camp?

Industry backgrounds, did they work in, perhaps, consumer electronics testing before they became an SDET at Microsoft? Were they at startups versus large enterprise companies, or somewhere in between? All those pieces of diversity are going to be influential and improve the health of the ecosystem of your team, and so those friend networks are important for getting candidates in the door, but understanding that that sometimes is going to lead to a certain amount of self-selection for candidates.

You have to, like in soccer, they say, “Run to where the ball will be, rather than where the ball is.” If you have those early conversations about who you need to hire, and what you want to look for, what sort of energy and person do you want to add to your team, to influence it into a good direction? And then go to those people, find them, whether it be through meetups or user groups, or extending your extended network, not just your immediate friend network.

Derrick:
Are there any other resources you can recommend for those looking to improve how they hire developers?

Kerri:
Looking at the different boot camps you’re doing, and how they’re talking to their students, as well as to their sponsoring companies, or the companies that are hiring. I’m a really big proponent of hiring more junior developers, because no one is ever going to know our exact technology stack and our exact way of working, we always have to teach people, so looking at what those boot camps are doing, and how they’re talking about the industry, because they’re trying to set people up for success over the next five years. There’s a lot of wisdom. They’re spending a lot of time to gather wisdom that they can relate to us about who we should be hiring over the next five years, and what skills we should think are important.

Finally, I tell everybody this, go take a relationship skills class. Although they’re sold as being aimed at couples, a lot of that is really about listening to other people and understanding what their concerns are. Once you can start to build those sorts of skills for understanding the perspectives of other people, just generally improves everything about your hiring process, and your team, and how you work with each other.

Derrick:
Kerri, thank you so much for joining us today.

Kerri:
I’m really excited about this topic. I’m glad to see more and more people talking about it. There’s no one size fits all solution. We all face some really unique problems, but there are some commonalities.

9 Effective Code Review Tips

9 Code Review Tips

For everyone:

  • Review the right things, let tools do the rest

You don’t need to argue over code style and formatting issues. There are plenty of tools which can consistently highlight those matters. Ensuring that the code is correct, understandable and maintainable is what’s important. Sure, style and formatting form part of that but you should let the tool be the one to point out those things.

  • Everyone should code review

Some people are better at it than others. The more experienced may well spot more bugs, and that’s important. But what’s more crucial is maintaining a positive attitude to code review in general and that means avoiding any ‘Us vs. Them’ attitude or making code review burdensome for someone.

  • Review all code

No code is too short or too simple. If you review everything, then, nothing gets missed. What’s more, that makes it a part of the process, a habit and not an afterthought.

  • Adopt a positive attitude

This is just as important for reviewers as well as submitters. Code reviews are not the time to get all alpha and exert your coding prowess. Nor do you need to get defensive. Go into it with a positive attitude of constructive criticism and you can build trust around the process.

For reviewers:

  • Code review often and for short sessions

The effectiveness of your reviews decreases after about an hour. So putting off reviews and doing them in one almighty session doesn’t help anybody. Set aside time throughout the day including breaks not to disrupt your own flow and help form a habit. Your colleagues will thank you for it. Waiting can be frustrating and they can resolve issues quicker whilst the code is still fresh in their heads.

  • It’s OK to say “It’s all good”

Don’t get picky, you don’t have to find an issue in every review.

  • Use a checklist

Code review checklists ensure consistency – they make sure everyone is covering what’s important and avoid common mistakes.

For submitters:

  • Keep the code short

Beyond 200 lines, the effectiveness of a review drops significantly. By the time you’re at more than 400, they become almost pointless.

  • Provide context

Link to any related tickets or the spec. There are code review tools that can help with that. Provide short but useful commit messages and plenty of comments throughout your code. It’ll help the reviewer and you’ll get fewer issues coming back.

9 Integration Testing Do’s and Don’ts

Integration tests check whether your application works and presents properly to a customer. They seek to verify your performance, reliability and of course, functional requirements. Integration tests should be run against any of your developer, staging and production environments at any time.

Writing good tests proving your solution works can be challenging. Ensuring these tests to perform the intended actions and to exhibit the expected outcomes requires careful thinking. You should consider what you are testing and how to prove it works – both now and in the future. To help you create tests that work and are maintainable, here are 9 Do’s and 9 Don’ts to contemplate:

When Creating Integration Tests Do…

1. Consider the cost vs. benefit of each test

Should this be a unit test? How much time will it save to write this test over a manual test? Is it run often? If a test takes 30 seconds to run manually every few weeks, taking 12 hours to automate it may not be the best use of resources.

2. Use intention revealing test names

You should be able to figure out or at least get an idea of what a test is doing from the name.

3. Use your public API as much as possible

Otherwise, it’s just more endpoints and calls to maintain when application changes are made.

4. Create a new API when one isn’t available

Rather than relying on one of the Don’ts

5. Use the same UI as your customers

Or you might miss visual issues that your customers wouldn’t.

6. Use command line parameters for values that will change when tests are re-run

Some examples include items like site name, username, password etc.

7. Test using all the same steps your customers will perform

The closer your tests are to the real thing, the more valuable they’ll become.

8. Switch your system under test back to the original state

Or at least as close to it as you can. If you create a lot of things, try to delete them all.

9. Listen to your customers and support team

They will find ways to use your systems that you will never expect. Use this to your advantage in creating real-world beta tests.

When Creating Integration Tests Don’t…

1. Write an integration test when a unit test suffices

It’ll be extra effort for no benefit.

2. Use anything that a customer cannot use

Databases, web servers, system configurations are all off limits. If your customer can’t touch it, your tests have no business touching it either.

3. Access any part of the system directly

Shortcuts just reduce the quality of your tests.

4. Use constants in the body of your tests

If you must use constants, put them in a block at the top of your test file or a configuration file. There is nothing worse than having to search through all your source files because you changed a price from $199.95 to $199.99.

5. Create an internal-only API

Unless necessary for security or administration.

6. Create an internal only UI

You’re supposed to test what the customer will see after all.

7. Make your test too complex

No matter how brilliant your test is, keep it simple. Complexity just breaks later. If you are finding it hard to write, it will be hard to maintain too.

8. Test more than one thing

Stick to what you need to test. If you try to do too much in one test, it will just get more complex and more fragile.

9. Leave the test system in a bad/unknown state

This means a broken or unusable site, database or UI.

 

A Guide to Open-Sourcing Your Project at Work

Congratulations! You’ve written something at work that is amazing and you want to share it with the world! This guide covers three key areas that you should consider before making the leap: Why, when and how to do it.

Why Should I Open-Source My Work Project?

Open-sourcing your project at work can be a great idea. It can:

Help you build a developer-friendly brand

  • From those with a developer-focused product, like Stripe and Twilio, to those with APIs, like Facebook, Google and Square. Open-sourcing your code can be a good way to build your company’s relationship with developers.

Allow you to give back to the community

  • Just think of all the libraries and software you use on a daily basis that make use of open-source code. Adding your own is a good way of paying it forward so that others can benefit from your contribution. We’ve open sourced a number of libraries and even whole products.

Help you to recruit

  • Take Yahoo and LinkedIn for example. They’ve found that through their commitment to Open-Source projects (like Hadoop and Kafka), that they’ve been able to encourage developers to join them who otherwise might not have.

Gain more contributors than your project ever would have in-house

  • Like for example Square’s Dagger, a dependency injector for Android and Java. Having released it, many developers are contributing to it, including those at Google. In fact, Google developers have been contributing more than Square’s developers do themselves.

When Should I Open-Source My Work Project?

There are two conditions that you would want to meet before open-sourcing your project. You want to make sure that:

It won’t hurt your business

  • It may be an impressive, complicated bit of code that would be useful for other products beyond your own. Yet if that development is your secret sauce, then giving it away would be bad for the business. Likewise, if your library is an integral part of what makes your product unique or even what makes it possible, then you might want to keep it in-house.

Your code is helpful to others

  • Consider whether anyone else would actually want what you’ve created. Is it so uniquely tied to your workflow or infrastructure that it wouldn’t be useful for others? As a rule of thumb: if making it suitable for general consumption would make it less useful for yourself, then it’s probably not worth the effort.

Ok, so you’ve met those two requirements. Then let’s move to the mechanics of open-sourcing some code.

How Do I Open-Source My Work Project?

Step 1: Audit your code for security leaks

  • Chances are higher than you might like to admit that you or a colleague have left some passwords, usernames, IP addresses, machine names, personal contact information or other security hazards somewhere in your code. Keep in mind that this applies not only to your final master code but also to all the changesets you’ve had in the past.

For that reason, we recommend you do two things:

1. Make a brand-new repository
    • Chop off all the history of the code up to that point. There will be a new history and it saves you having to audit all the historical versions of your code. Plus, no one needs to know that it took you two weeks to wrap your head around C++11 lambda syntax.
2. Audit the code for security problems
    • This will take a lot less time than you think. Look especially at test suites and any places that are near connection points to other systems.

Step 2: Strip your code of profanity and immature pot-shots

  • While you’re in there, also rip out anything inappropriate that makes you sound more like a teenager than a professional. This doesn’t mean you can’t have any humor in your source code. But it does mean that jokes made at the expense of your competitor, a customer or the decrepit browser you’re forced to support might not be appropriate.
  • If in doubt, think about whether you’d feel comfortable reading your code loud to those beyond your team.

Step 3: Make sure your code adheres to best-practice naming and formatting

  • You’ll want your open-source code to be examples of your best work. Make sure you are using good, standardized naming conventions and formatting. Use tools like pyflakes/pep8, jslint, gofmt, ReSharper and others to help.
  • Also, keep in mind that if you’ve been wanting to do the One True Naming Standardization for your project, now’s a good time. Once you open-source your code, there will be a lot of inertia to avoid breaking changes. Get those done before you release. It’ll also make it easier for other contributors to get started with your code.

Step 4: Document it

  • You don’t have to write ninety pages of info docs but you should at least have a nice Markdown-formatted README.md in your root directory that explains what your software is, how to use it, and (if applicable) how to build it.
  • If you’re releasing a library, you should also make sure your code has docstrings/JavaDoc/whatever so that you can generate API documentation.

Step 5: License your code

  • You may want to get some proper legal advice on this. But before releasing your code, you should pick a license. Unless you have a compelling reason to do otherwise, the MIT license will probably suffice. It’s short, sweet, well-understood, liberal and makes integrating third-party changes back into your own products headache-free. But if you’re contributing to the code that you want to include in a project that already has its own license, you might want to use that license instead. Here’s a useful overview of license types for more info.
  • You’ll want to put a LICENSE file in your repository and have a copyright notice somewhere prominent — either in that file or in the README. Such as ‘(C) 20XX Your Name. All rights reserved.’

Step 6: Name your library or tool

  • Pick a name. Make sure it’s not offensive and avoids having the same name with other existing libraries and trademarked products.

Step 7: Push your code

  • Put it on GitHub, create your own organization, repository and push your code.
  • Keep in mind that some communities have secondary systems that you should consider utilizing as well. If you’re writing .NET, then another one might be Codeplex. If it’s Ubuntu-specific then a Bazaar mirror on Launchpad etc.

Step 8: Publish your package in the appropriate package archive

  • If you’re publishing a library, submit it to the appropriate package manager. For .NET, that would be NuGet; for Python, it’s PyPI; for Perl, it’s CPAN; for Ruby, it’s RubyGems; for Node, it’s NPM; and so on. Also, make sure that someone else at your company, such as a sysadmin, has the ability to continue maintaining the library under the unfortunate circumstance that you get hit by a bus.

Step 9: Announce your code

  • You’re all good, time to announce it! You’ll want to blog and tweet it out. You should also consider publishing on /programming on Reddit and Hacker News etc.

And that’s it! You’re all done!

…well, nearly.

Step 10: Don’t forget about your code

  • Just because you’ve published it doesn’t mean you’re done. You’ve unleashed a new-born into the world; you need to take care of it. Monitor pull requests and bug reports on your new project. If you realize that keeping your project going is overwhelming, then a hearty congratulations! You should remember that it is your responsibility to at least find an extra or substitute maintainer. It’s okay if your project ultimately forks but it’s best not to do so just because you dropped the ball incorporating freely and submitted improvements to your code.

That’s it. For real this time. So go out, contribute, and have fun!