Three Tips to Produce Easy to Understand Code

Code-01

From working the last 6 plus years in the web industry, I’ve come to learn a good bit about working as a part of a development team. In development, a lot of thought goes into how to structure, name and organize code. When you work alone, this really becomes less of an issue. The piece of code that you leave in one place, is there exactly where you expect to find it when you come back. Working with teams brings the benefit of more horsepower, but unless you are intentional about being in sync — you run the very high risk of wasting a lot of that potential power as a team.

While writing performant code is always a primary focus, I’d argue that writing readable, quickly understandable code is almost just as important. Many times I’m faced with a situation where writing performant code is easy, but writing code with a low level of cognition is the challenging part. Here are three quick tips I’ve learned to produce easy to understand code:

1. Be Consistent

Be diligent about maintaining patterns in your code. If you decide to order your CSS attributes by the alphabet (I do), then do not break that habit anywhere. Get together has a development team to have open, inclusive discussions about the best way to write your code syntactically. Your team may have lots of differing views, but avoiding conversations about them is only going to slow your team down. Come to the table with an open mind and a goal of improving the entire team’s efficiency.

2. Provide Mental Breaks

A problem I see often is large, complex chunks of code. Whether this is a single file with 900 lines of back-to-back HTML or it’s a JavaScript function that performs six very different tasks. Consider inserting line breaks in to HTML providing a buffer between “blocks” of common HTML. Take the giant JavaScript function and split it into five or six separate functions to promote separation of concerns. There are plenty of ways to reduce the complexity of code, but looking for areas to give your fellow teammates mental breaks is a nice favor.

3. Pretend to be a Coworker

When organizing, naming and writing code, take opportunities to ask yourself “if I were to be given this code base with no prior domain knowledge, would I understand what is going on?” If the answer is no, then you aren’t doing a very good job of preparing your next teammate for success.

It’s easy to live in the moment and say “I’m the only one that is ever going to touch this code”, but nine times out of ten that I’ve said that it’s turned out to be untrue. Make attempts to push that mindset away and always be on the look out for your teammate that’s opening in your code next.

These are just a few tactic that I use when I’m writing code. What are some steps you take to improve your teams efficiency? Let me know in the comments below.

Share This
  • http://joshcrews.com joshcrews

    I agree, especially on naming stuff in code. Good names (variables, functions) should say as readably as possible exactly what the thing does, and you should make sure the thing does no more or no less than what the name is.

    So `def remove_all_whitespace` should do just that and only that.
    So much code could be upgraded from just getting naming right.

    • http://davidcalhoun.me/ David Calhoun

      Yep. The little things like appropriate, concise names add up to have a large impact. It’s easy to let it slide, but it’s well worth the investment when working within a team.