Here’s an example of a good code sample for entry-level programmers.
I review a lot of code samples, both for work and for pleasure. I think the difference between an average developer and the greatest developers is that the latter group reads more than they write. How can we improve our skills as developers if we don’t look at code written by others to learn what’s new, useful, and helpful? I read samples, examples, tutorials, production code, research code, test cases, code in languages I don’t know, code from “top coder challenges,” and any other type of code I can find. I also review code samples from job applicants. The most common responses I receive when I ask for a code sample are “Really?” or “I don’t have a code sample. Can we skip to the interview?” I wish that was the worst of it: When I was a line manager, over half of my job applicants ghosted me when I requested a code sample. This is especially funny since my job posts included a special section that said “We will request a code sample from you.”
Let’s assume that these things happen because people don’t know what a good code sample looks like. If that’s the case, here are some suggestions for writing a good code sample. They also work well for learning new languages.
Distribute code you’re allowed to share. The most important thing about sharing a code sample is to only share code you can legally share. Never give someone a sample of proprietary code that you wrote for work. Don’t even suggest it. Take an hour to write a good sample, push it to GitHub, and then finish watching Future Man, Star Trek: Discovery, or the ballgame that you had on while you slung it together. On the other hand, if you work on open-source projects for a living, feel free to submit one of your open-source codes and suggest reviewers run Gitstats or something to see your contributions.
Include five or more classes that demonstrate a good design philosophy. Show off how well you understand object-oriented concepts such as inheritance, realization, and delegation by creating a simple-but-thorough design with distinct classes. This not only shows how well you understand the concepts but also that you can design things well. Plus it demonstrates that you know basic things like how to call functions.
What if you don’t plan to use classes for some reason? Maybe you’re a functional programming advocate or the job requires skills in Fortran 77. Whatever the case may be, you should still show that you can design a code with five or more discrete units of computation and well-organized data. This can include functions (every language ever), derived types or typedefs (Fortran and C), or multiple dispatch (Julia).
Do some I/O. Showing some input and output (I/O) operations in your code demonstrates that you know how to manipulate data and how to use logic and loops since input and output data usually come with edge cases and in bulk. More experienced developers will quickly concede that about 60% of all our time writing code is doing I/O in one form or another, so it is an incredibly important skill to demonstrate.
Show some tests. Whether or not the job will require a lot of software testing, showing how much you know about testing only makes you look awesome. If you don’t know about testing, then treat yourself to the Wikipedia articles on software testing and unit testing.
Use Git. Git is the most commonly used version control system in software engineering. As with testing, this is a technology you want to show you know something about even if the team still uses SVN or – banish the thought! – CVS.
Include a build system. This might not seem like the most obvious thing to include in your code sample, but it’s important because reviewers need to know that you know how to build your code. The need can be explained by shamelessly stealing and butchering adapting one of the best lines in the movie “Three Amigos:”
Well, you told me your code sample has a build system. And I just would like to know if you know what a build system is. I would not like to think that a person would tell someone he has a build system, and then find out that that person has no idea what it means to have a build system.
Is it ok to use an auto-generated build system from an IDE? If it can be used without starting the IDE, like a Makefile or Maven script, then yes. If not, no. (Read that as “Whatever Visual Studios does by default is not good enough.”)
Document your sample. The single biggest problem I see with code samples is that there is no documentation. I don’t care how “self-documenting” you think your code is, I don’t have a clue what it’s supposed to do and you won’t either in five years. More importantly, API-level documentation and skills with Javadoc, Doxygen, etc. are crucial in modern development shops. No user off the street is going to know how to use char ** getVal(int a, const int & a0, const double & a1) const; correctly! Furthermore, did you include a README.txt or README.md file to tell me what functionality your code offers, who wrote it, and how to contact the author? Does it have a license?
Make it pretty. Presentation matters. You’re probably worried about being dressed nicely to make a good first impression—shouldn’t your code also be “dressed nicely” to make a good first impression? Clean code is more readable than messy code and makes the review process easier. It also speaks to your ability to support development in a collaborative way.
Be transparent. Don’t lie or hide things about your code sample. Put issues – good or bad – out in the open, be transparent, and own it. If reviewers don’t like something in your code sample, adopt a growth mentality and ask them if they’ll let you fix it and submit it for re-evaluation. If you do something in your code sample that you know is wrong, document the reason why you did it with something such as: “A realistic implementation would replace this version that scales a random number from rand(), but this is sufficient for my code sample.”
I hope this helps you write a better code sample. I wrote a simple code sample that you can check out on my GitHub page. If you have questions or want to complain about either this article or the samples, drop me a Tweet at @jayjaybillings or leave a comment below.
Jay's Whiteboard 