How many times have you listened to a developer talking about following the clean code principles? Are you aware of the advantages of writing clean code? Does the project you are working on have a proper architecture? We often leave the basics aside and start writing code without thinking in the long run, regardless of the expenses (time and budget) that could be saved. We, at Mayan Technologies Inc., strive through delivering quality, maintainable and scalable products by not typing code careless but applying several principles, which I want to share in this blog entry.
In my opinion, the most important part of developing a new product is the Software Architecture. Keeping it simple, the software architecture is a set of rules that everyone involved in the development must follow. It includes set of tools, technologies, frameworks, programming languages and a proper abstraction of the desired product. The latest most be the top priority for us. If we create a good abstraction, e.g. decide which modules and components would exist, we can provide the product with scalability and maintainability, and survive to any unexpected change request from the client. Although many other benefits can be listed in here, most of the times I’ve found certain opposition from clients when talking about the time scheduled for creating the product architecture, resulting in a poor document created in a short time which nobody cares. However, having a good software architecture doesn’t require an extensive document (which nobody would care neither), but a simple and concise set of statements for guiding the process. Below, you will find a drawing[1] from Simon Brown[2].
As Brown shows, it’s more relevant to have a friendly software architecture guide the whole team understands and actually applies.
Prior to the development phase, it is also important to fix some code guidelines in order to create a "clean code" product. If the whole team understands and works according to the same standards, then everyone would be confident with anyone's code, resulting in a flexible and agile development. On the other hand, lack of standards agreed in advance produces several code which may actually work though nobody figure out but the author. Furthermore, when the team members have to leave the team, their not-friendly code stays and consumes a lot of effort from the others to continue working on it. For me, the most relevant advantages of writing clean code are:
1. Saves a lot of time: When you don't follow best practices and revisit your code from four months ago, you may not be able to recognize it. You put your efforts again to find out your own logic, variables and methods while telling yourself "Why did I write this?". And not to mention when someone else does. Keep in mind you work in a team.
2. Support maintainability and scalability: Adding a new module or even changing an existing one would become into a nightmare if you didn't follow a proper pattern. When you follow good practices and, for example, the client requests to add a new field in project's details, it should be as easy as adding a new property in project's model class, i.e. as easy as pie.
3. Easy to debug: You aren't just responsible of creating a pleasant looking product. You are the one who stands when the bugs and broken features arise. If you don't configure logs, write everything in one file, no method calls, then you won't know what's going on. Even worse when the error is a weird situation present only in your client's device. Always be prepared for the worst.
4. You're not the owner: You develop a project for a client. Then, you deploy when it's ready. Your job seems to be done so far. Does the client pay for the built and deployed product only? Not at all, it actually pays for the source code. If he wants to modify the product later, then he should be able to. So, be professional and deliver quality.
If you are a programmer, you must know there is a huge amount of books regarding clean code, good practices and code design patterns. It's a whole science by itself. However, you don't need a master degree in Software Engineering to create quality code. From the endless lists of good coding practices, I always recommend the four below:
1. Meaningful names: As simple as it may sound, choosing a meaningful name for your class, method or variable is the most appreciated attribute from a team member. Try to be obvious, concise and short. Everyone must figure out what your variable stores, what your method does and what your class refers easily.
2. Follow the Single Responsibility Principle (SRP): Classes and methods must be small and perform one and only one task. Try to avoid nesting IF statements that are hard to understand, instead you can use sub-functions (using straight-forward names, as we just said). If something is easy to understand, it's easier to maintain.
3. Be careful with functions' side effects: Side effects make extremely difficult to create bug-free code. Side effects are modifications done by a function without explicitly letting the function consumer know about those modifications. The consumer would have to read the whole function implementation to figure out the side effect, if any. Try using getters and setters, instead of a huge function which alters several UI elements, global variables and trigger asynchronous procedures at the same time (remember the SRP).
4. If it isn't tested, it's broken: Write and run tests, a lot of them, especially unit tests. You must be able to find bugs and even prevent them before the customer notice the broken feature. Also, this would help you to realize when you break an existing piece of code when integrating new features.
Finally, think of your customers and teammates when writing a new module or declaring a new variable. Think of your future self. Don't type code first and then waste time fixing. First, calm down, think and design your code, then type and enjoy the result.
References: [1]: Sketchnote created by Urs Enzler and published under the Creative Commons Attribution 4.0 International License. (https://creativecommons.org/licenses/by/4.0/)
[2]: Simon Brown. Author of Software Architecture for Developers and creator of the C4 software architecture. (http://www.codingthearchitecture.com/authors/sbrown/).