Aspiring software engineers are often asked for code samples to demonstrate that they’ve got some clue what they’re doing. This is pretty terrifying and it’s incredibly difficult. When they’re not done well, they don’t provide much in the way of useful information.

I’m a lead engineer at a pretty cool software company. I’ve been in a lot of interviews and I’ve read a lot of crappy code samples. I decided to write about what would get me excited about a candidate’s code sample (and, by extension, them). Other people might feel differently. That’s cool; this isn’t a math test. (But I would love to hear those counter-points in the comments below!)

What’s a Code Sample For?

A good code sample is one that allows someone to get an idea of your ability as a programmer with a minimal time investment. Code samples are three things:

1. They’re marketing tools — Good engineers are good communicators. Crafting an excellent code sample requires you to think about what you want to say, think about who your audience is, and then get to the point as expediently as possible.
2. They’re intended for engineers — The job of evaluating your code is going to fall to a senior engineer or hiring manager. A well-curated code sample saves that person a lot of time, and they will appreciate that immensely.
3. They’re examples of your programming ability — people reviewing your code sample will ask themselves questions like “is this the kind of code we want in our codebase?” or “will this candidate be able to work with our existing code?”

The less you have on your resume, the more vital a code sample is. If you’ve got years of professional programming experience, the odds that your code sample will convey more information than a 15 minute conversation with you is almost zero.

What makes a good code sample?

With those three things in mind, here is a list of hints for making the most of your code sample:

1. First and foremost: have one — Have a specific repository or page on your website dedicated to your code sample. By itself, your GitHub profile is likely to be only slightly better than nothing; it’s not a substitute for a well-curated sample.
2. Leave out the boilerplate — Pull out the code you wrote. Don’t make me wade through dozens of auto-generated files to find the meat.
3. Have lots of READMEs — Your code sample should have an overall README and one for each section/sample/snippet. Be descriptive. Tell your reader what they’re going to see and then show it to them.
4. Add more comments than normal — Since you’re going to be pulling classes, functions, and snippets out of context, some extra comments to explain things that might otherwise be confusing will help. Don’t go overboard, but try to avoid letting unknown things be distracting.
5. Each snippet should have a purpose — For every file, function, class, or snippet you add to your code sample, know what you’re trying to prove. Familiarity with databases? Ability to write semantic HTML? Metaprogramming? Whatever it is, have a point.
6. The code you present should be “good” — Whatever that means. Code you wrote in the final hours of a hackathon to fix a nasty bug does not have to be polished to the same degree as the method you wrote in your last internship that went into a live system.
7. It should be edited and clear — Remove distracting or messy blocks and replace them with a well-named hypothetical function and a comment describing what’s going on (but don’t include that function in the sample). This is especially good for blocks of code you copied from the internet to work around some language or framework limitation.
8. Don’t try to perfect it — A candidate presenting a “perfect” method is no more impressive than the candidate who shows the imperfect one but understands its limitations. Make sure to be clear about that understanding in comments and/or the README.
9. Nobody’s going to actually run your code — Do check your code for syntax errors, though. If you’re pulling out small enough snippets, someone might copy and paste them into a terminal just to see if they work as advertised. This is more likely with stand-alone algorithms and less likely with code you pulled out of a working application.
10. Be concise — If it takes too long to figure out what’s going on, the reviewer is probably going to just assume you’re not very good — either at programming or communicating about code, both of which are vital skills for programmers and engineers¹.

What if you don’t have a code sample?

Depending on the level of job you’re trying to get and the amount of time you have, this can be overcome. If you can put aside a few hours, you can produce enough to show a prospective employer that you can actually write code. If you’re looking for ideas, you can find some simple challenges on sites like exercism.io or CodeKata. No need to use their whole system, just find an example that you think you can do.

Aside to employers: understand that a strict code sample requirement is going to filter out some excellent candidates and can contribute to the lack of diversity on your team. Make that tradeoff carefully.

Talk is cheap! I want to see an example!

Okay, fine. I put together a sample code sample, which you can check out on GitHub. Feel free to do all of the GitHub-y things — forks, pull requests, issues, etc. — if you see anything that ought to be changed.

It took me a couple of hours to put that together, which is just to say that it’s not a trivial endeavor. Prepare to spend some time on your code sample, especially if it needs a lot of cleanup or explanation.

1. The irony of asking people to be brief in a 1,000 word essay is not lost on me. ↩