Applying Design Concepts to Code — Part III

On many software projects, there are some questions that get asked regardless of the domain of the problem being solved. The answers to these questions are heavily influenced by the scope of the project and people working on it. Can we take what we’ve learned about design from parts one and two and apply it to these questions to sharpen our thinking and make our projects more enjoyable to work on?

Q: Should I have a code style document for my project?

A: A code style document is a cultural constraint. It is a way to restrict the way the code is written in the code base. If someone ever submits code that does not conform to the code style document, you will be absolved of all guilt when requesting a change to some code that doesn’t adhere to the style in your code base — just point to the code style document! Consistent code throughout a code base makes it easier to read code from file-to-file, which ultimately makes maintainence easier.

Pro tip: if a linter is available for your language, you can use it to enforce coding style as a prerequisite for merging code.

Q: What should I test?

A: It depends on the type of testing your team is doing. Perhaps a good way to answer this question is with another question: what functionality is being promised to the consumer of the code? You should probably test the promises to the user are satisfied and error cases are handled appropriately.

Q: How much should we think about architecture/design patterns?

A: Design patterns are effective ways of communicating conceptual models quickly. When applied appropriately, the code in your code base can be intuitive and easy-to-use. When applied haphazardly, you can end up with a code base that makes comprehension, maintenance, and implementing new features difficult and/or time-consuming. Be careful of using a blanket-rule to always apply a specific design pattern to every part of your code base — comprehension may be easy, but maintenance and adding features may become time-consuming.

Q: Why should I care about applying design to my code?

A: In his talk, Simplicity Matters, Rich Hickey talks about working with a code base that eventually turns into elephant-sized behemoth. Once you’ve reached that point, your code has a seat at the table when you’re thinking about adding new features. If you haven’t been intentional about design, you might find yourself in a situation where adding a seemingly-trivial feature becomes non-trivial. You don’t want to put yourself in a situation where your code is dictating how you work.

Q: How should I think about writing my commit messages?

A: A commit message is a signifier that describes a group of changes made to your code. Good signifiers make your code easier and more enjoyable to maintain. Poor signifiers make your code frustrating to maintain. Here’s a great article on how to write a quality commit message.

Q: Should I restrict the number of lines of code in the functions that I write?

A: The answer to this question is dependent on the code being written. For instance, I’ve heard the code on F18 fighter jets is one long, continuous function. This makes sense for such critical software. For object-oriented code bases, one continuous function makes less sense. I was taught in college that functions should start and end within the height of a screen — this ensures the function can be read/understood without requiring scrolling. This makes intuitive sense, but the number of lines in a method probably should not be the reason for altering your design. Rather, a long function can be a good indication of too much functionality being wrapped up into one function.

Q: What should I put in the README for my project?

A: Consider the README as the introduction to your project. Think about the questions that someone may have when getting started and put the answers to those questions in the README. For example, “How to I build and run this project?”, “Where do I find the assets for this project?”, “Is there a code of conduct?”

Q: Should I write documentation?

A: Some people claim that comments in code are unnecessary and only add to the amount of maintenance because they believe that code should be self-documenting. It’s certainly admirable to strive to write code that’s so clear that comments aren’t needed. But when writing code we have the advantage of having a lot of context and domain knowledge of the part of the system we’re working on. When consuming code, we won’t necessarily have that advantage. How do you write self-documenting code when edge cases are involved? Another important consideration is that your code might be someone’s introduction to the code base. Writing comments can improve the experience of the person using your code and save frustration. Comments are one of the six design components — why not utilize them to communicate your design to your users?

Q: How should I think about organizing the code in a file?

A: Organizing your code is a form of constraint. For example, if you know that methods and properties are always alphabetized, you know exactly where to look for a method named removeItem. Alphabetization is a good default for organizing code, but it can make sense to organize the code in other ways depending on the project. As long as the organization is consistent, you can't go wrong!

What other project-level questions can you answer by leveraging design concepts?

This has just been a sample of a few questions that we can answer through applying design concepts. Next time you have a question on one of your projects, try applying the design concepts outlined in parts one and two to help you reason through the question.