Writing Code for Your Future Self

One of the greatest things about the web industry is the respect and generosity developers have for one another to share knowledge in this ever-changing atmosphere. Whether you’re on a small or large team, solo coder or open-source hero, arguably the most important pieces of your code aren’t code at all. Commenting and writing readable code can save yourself and teammates valuable time by quickly understanding what your code does without the countless hours you spent carefully crafting the most elegant code imaginable. Even if you’re working alone, readable code can avoid those awkward situations of you having to figure out what genius (spoiler: you) wrote this awfully convoluted code. Other benefits include auto-generated documentation and speedier code reviews. So, next time you write the “one function to rule them all”, take the time to rename it from doesSomething to addTaxToSubTotal and comment the hell out of it – your teammates and future self will thank you.

What is “Readable” Code?

JavaScript: it was the best of languages, it was the worst of languages. Because of JavaScript’s flexible nature, we can sometimes write code that looks very strange and hard to read. Here are a few guidelines you can follow to ensure you are writing readable code:

• Describe: Use descriptive variable and function names, even if they take longer to type. In six month from now, you’ll have a much better chance of understanding what a function does if it’s called getAllCustomerNames rather than getData.
• Simplify: Don’t over-engineer your logic to the point of unreadable complexity. Saving a few lines of code while giving up readability is not worth it in the long-run.
• Comment: Complex logic is sometimes unavoidable. When it’s not abundantly clear what your code does just by looking at it, comments can lend a helping hand in plain english. Don’t shy away from lots of comments either. Techniques like minification will strip out all comments for production code, so you don’t waste any precious bytes.

Refactoring for Readability

Let’s take a look at some code that could use help to make it more readable. Below we have a function that performs some actions on product information. I will refactor the function so that it performs the same actions, but is much easier to maintain and collaborate on.

function changeData (data) {
  if (data.price > 100) {
    data.label = "expensive";
  } else {
    data.label = "cheap";
  }

  return data;
}

This function is pretty simple, it takes a data object and sets the label property to “expensive” if its price property is greater than 100, otherwise sets it to “cheap”. Although this logic is simple, there are a number of changes that could be made to make this function much easier to read and maintain.

• Function name: “changeData” is not a very descriptive name. Since this function is changing product data in a very specific way, we can name the function as such. This will also help developers understand what the function does when it is called elsewhere in the application.
• Function parameters: “data” is obviously not descriptive at all. We should rename this to best reflect what piece of data is being brought into the function.
  Verbose logic: The if statement could be simplified into a ternary statement since there are only two possible outcomes for the label property.
• Commenting: We are missing comments for this function, which could provide some great context to the maintainer.

Let’s see what the refactored function would look like:

function setProductLabel (product) {
  /**
   * Set the Product label based on its price.
   *
   * @param {object} product The Product object to update
   * @param {int} product.price The total price of the Product
   * @param {string} product.label The current label of the Product
   * @return {object} product
   */
  product.label = (product.price > 100) ? "expensive" : "cheap";

  return product;
}

ProTip: Put the comment block inside the function so that if you print the function in a console log, the comments print with it.

Conclusion

Writing clean, readable and well-commented code is a skill that needs to be honed and valued. Many developers overlook this, but it’s really what can set you apart from others in your field. And remember any little bit helps, so use the guidelines above to gradually improve your code today!

Any questions, thoughts, ideas? Let us know!