How to Make Your Code Stand out to Interviewers
While reviewing the projects of job applicants, I’ve noticed a major difference in the code of the candidates we go forward with and the ones we don’t.
The code they write, to put it simply, is beautiful. And I don’t mean because it’s necessarily amazing code; I mean that it’s easy to look at and I want to keep reading it. It’s consistently styled, descriptive, documented, and I just can’t take my eyes off of it.
The world could certainly use more code like that. If you’re a new developer, having trouble getting bites on your applications, or just want to make your code more professional, here are some easy techniques you can begin implementing to make your code more desirable:
- Use version control more professionally
- Use semantic naming for variables and functions
- Include comments and documentation
- Lint for consistent style
- Write automated tests for your code
Throughout this article, we’re going to use these suggestions to improve this purposefully bad code to show that even though you might not be a senior developer yet, they can vastly help improve the look, and quality, of anyone’s code.
Although this article focuses on JavaScript, the concepts within are applicable to most, if not all, languages.
Version Control
Do you have any publicly accessible code for potential employers to look at? It’s important to be able to show them that you know how to work in a project-structure that’s protected by version control. If you don’t use any type of version control hosting, like GitHub or Bitbucket, please start. Although employers might not spend too much time going through your public code, we do like to peruse to see what kinds of things you’re interested in making, and of what quality.
If you don’t know how to use git at all yet, here are some resources you can learn from. Keep in mind that no matter which article you read, you can still use any host you want. The concepts apply to any git system.
When using git for your own projects, make sure to use branches instead of just pushing to master. This is more like how a proper team would work and shows that you’re smart enough to be careful.
Learn to be aware of what your commit messages look like to other people. They aren’t just something you need to do to be able to push your code, they’re a crucial form of documentation in a code base. Also, when viewing a project repository on GitHub, the landing page shows the most recent commit message that affected that file. Interviewers definitely see them. If you want to learn how to write better commit messages, Chris Beam’s blog post on how to write better commit messages provides some fantastic patterns to follow.
Semantic Naming
You know what’s nice? When you can understand what code is doing at a glance. In programming, there’s an old adage that, “good code is self-documenting” and you should always write with that in mind. You should try to write your code in a way that it can almost be read like a sentence.
Variable naming
Looking at the example above, can you instantly tell which is easier to read? Please don’t make people do mental jiu-jitsu to understand what your code is doing. If you name variables by what they’re meant to represent without unnecessarily trying to shorten them, your code reads more like a story with a purpose than a cipher without a key. And at the very least it avoids readers having to scroll up to remember what in the world t stands for.
Abbreviated names were originally used to save memory in older programming languages. Thankfully in JavaScript, we don’t have to worry about that so you can get as descriptive as you want with your variable names. If you do want to save space, minify and obfuscate your code for production instead of making the rest of us suffer by trying to do it yourself.
Writing descriptive variable names and following some common stylized naming conventions will further help people understand what a variable is. These naming conventions focus on the type the variable is. Some examples are PascalCase for classes/constructor functions, state-prefixed roots for booleans, UPPERCASE_SNAKE_CASE for important, higher-scoped constants, or a $ sign preceding jQuery objects. Although not everyone follows these conventions, they’re well enough known that experienced developers will recognize the purpose they serve.
Function Names
Function names should start with verbs to denote that they perform an action. For example, getters and setters on an object should be get[PropertyName] or set[PropertyName]. A function that makes an AJAX request for getting product details could be named fetchProductDetails.
However you name your function, try to be as clear as possible about its use and intention. If you’re having trouble naming your function because it doesn’t just do one thing, that’s usually a sign you should refactor it into multiple, smaller, functions.
In our code example, I’ve renamed all the variables to full words, renamed our order function, and even made a new one. Our new little function getProductPrice is pretty simple, but it’s a helpful little bit that we can reuse. It’s also self-documenting by name alone because it tells us exactly what it’s doing. Our original function, order, was renamed to calculateTotalPrice in order to be more descriptive of what it’s actually doing.
Comments & Documentation
Sometimes semantic naming can only get us so far. Other developers could spend hours reading through and trying to understand your code base, but do they have the time and desire to? Probably not. What if you could just tell them what your code does and save them some time?
If you don’t write comments in your code because you ‘understand what your code is doing,’ clearly you’ve never looked back on your code after a few weeks of not working on it. If you’re having trouble understanding your code, other developers definitely will. So do everyone, including yourself, a favor by adding comments to your code as you go.
However, with great comments comes great responsibility. Be wary of over-commenting and making your code more cluttered. Comments shouldn’t explain every little thing that you’re doing. That’s what semantic naming is supposed to help with. Other developers should be able to follow along well enough but they might not know why you wrote certain blocks. Try to use inline comments for explaining your intent.
Documentation Comments
For functions, it’s helpful to write a small explainer above them. This serves as a small form of documentation. Depending on what style you write your comments in, they can even be used to create actual documentation!
One popular style for writing comment docs is JSDoc. Through plugins like Docblockr (for Sublime), you can easily add auto-filled comments in this style. If you then decide to create documentation from them, there are tools that can do that automatically. Check them out in the JSDoc Github repo.
Writing comments like this can be another helpful way to realize you might need to refactor a function. If you can’t sum up what a function is doing in one sentence, it’s probably time to split it up into several smaller functions that can be.
README, please
READMEs are markdown files that source code hosting sites like GitHub and BitBucket will display as formatted text when viewed in your repo. Every project should have at least one README.md. This is usually the first introduction to your project. If no one can understand what your project’s intent is, how to get it started, or can’t find any info about it, they probably won’t care about it.
For an in-depth guide on what to put in a README, check out the Art of README. If you don’t have that much information to write, don’t feel bad! Just put in what you can. Use the READMEs from repositories you like as examples. And if you’re like me and constantly need to reference how to write markdown, here’s a handy markdown cheatsheet.
Here we’ve added little comments showing what our functions do, what types their parameters are expected to be, and what value our functions might return. In JSDoc notation, string[] means an array of strings, and number|undefined means number or undefined. These are helpful for seeing how to work with a function at a glance.
Linting
Sure, maybe you’ve got a good eye. Maybe you even have your own personal style of writing code that you think looks nice. Or maybe you’re a spaghetti cowboy who thinks ‘no errors, no problems.’ Truth is, either style can benefit immensely from a linter.
A linter is an extension in your text editor or IDE that enforces style rules. So instead of you trying to manage yourself, it will highlight and show you exactly what rule you’re breaking. It’s super distracting to see the highlighted errors and incredibly therapeutic to fix them.
In the screenshot above, it’s warning about preferring dot notation over bracket notation, using let or const depending on if the variable gets reassigned, missing or extraneous semi-colons, and odd, or inconsistent, spacing.
Linters are for more than just style though. Many code style-guides include rules for things to avoid and reminders of best practices. For example, there are rules like no-unused-vars that error when you declare but never use a variable, or no-global-assign that yells when you try to reassign properties on native objects or read-only global variables. These can catch bugs before you push them and save you from some debugging hell in the future. It’s also a great way to learn some new best practices while you’re writing.
Setting up a linter
For JavaScript, the current most popular linter is ESLint. It’s easily configurable and integrates into most text editors like Sublime, Atom, VS Code, and a ton of others. It comes with a set of default recommended rules you can easily enable, or you can set up your own custom configuration. ESLint also allows you to extend off of outside style-guides. Brandon Morelli’s article on style-guides shows off some popular ones. Personally, I like to extend off of Airbnb’s Javascript Style Guide and customize a few rules from there. (Four space indentation is better than two. Sorry, not sorry. 😉)
If you’ve never used it before though or maybe just need a refresher, there are tons of great tutorials on learning how to get ESLint set-up. And here are a few to get you started:
- ESLint’s official documentation
- Why (and how) to use eslint in your project by Node.js Foundation
- Up and Running with ESLint — the Pluggable JavaScript Linter
If you prefer something simpler with less complex configuration options, JSHint is also great. Treehouse has a nice, quick, blog post on setting it up.
Introducing linting to your engineering organization
If your company doesn’t use a linter yet, try to get them on board as soon as possible! The quality of everyone’s code will improve by eliminating simple bugs early on, and you’ll be able to read through pull requests much faster when everyone’s style is consistent. First setting up a linter can be a difficult process because you need to have everyone on board with what rules to include. You know the whole spaces vs. tabs fiasco? Now imagine that with spaces vs. no spaces around if statement parentheses. The easiest route would be to go with one of the popular, extendable style-guides I mentioned before and then lint files the next time you’re working in them.
Testing
Now that your functions are smaller and serve a singular purpose, they’re much easier to test! If you don’t know how to test your code, or simply haven’t been adding tests to your personal projects, right now is the time to start. It makes your code look immensely more professional and gives you peace of mind when making future changes to your code.
Writing tests is a great way to show how your function should behave. If across your code you’re using a function that is expected to return a number, and then someone goes and makes a change to it so it now returns undefined in some cases, they’ve just introduced a possible JavaScript error. However, if you had tests, it would’ve been caught beforehand.
Test your methods for the expected return values and how your function handles incorrect arguments passed to it. Eric Elliott outlines the things you should make sure to test for in his article “5 Questions Every Unit Test Must Answer.”
While writing tests you might notice improvements you should make to increase the resiliency of your code. For example, while writing this simple little test for calculateTotalPrice, I realized that it would break if it was called without any arguments. Now I know to go back and add a type check for productList being defined and being an array. Then I can go and add tests to check it works in those cases to make sure I don’t have to worry about it.
Adding testing to your workflow
Vitali Zaidman wrote a great write-up of the state of current JavaScript testing that I recommend as a good starting point for research on how to get started with testing. I also recommend James Sinclair’s Gentle Introduction to JavaScript Test Driven Development.
If you enjoy the extra sanity tests can give you, try considering switching to a test-driven development (TDD) style. TDD is when you write your tests first before writing the actual code. Of course, they’ll all fail initially, but then as you’re writing, you make them pass. It’s like an outline of what you need to write. And SitePoint has a nice intro to TDD through examples.
If we had started with a TDD workflow, we would’ve had safety nets up for any potential flaws in our code to begin with. It would’ve saved us from having to go back and amend the code to add those type safety-checks because we would have known in advance to watch out for that.
Lookin’ Good
What do you think of the before and after of our coffeeShoppe example? The functionality stayed about the same but it looks a lot more professional now. Which development style would you rather work with? If you start using these suggestions in your workflow, it will make a noticeable difference to anyone reviewing your code.
A crucial part of these changes is that you show the interviewer you don’t need to be taught these things. They’ll see that you’ll be more likely to be able to contribute in a meaningful manner sooner than another candidate because they won’t have to waste time teaching you as much. Adding these techniques in your workflow will boost your potential value as an employee which can increase your chances of being hired. Plus, improving your code is a reward in and of itself. 😉
We’re hiring! If you already follow all of these practices and you’re looking for a new team, check out careers at Splash!
