Coding guidelines: programmer’s daily bread and butter

As we work in startup, we are under time pressure to release a lot of new features on time, features which do not have well defined requirements and the complexity of those features is often underestimated and we end up taking a lot of shortcuts / adding hacks to release such time sensitive features.

This may work for a short time, but over the period of time we realize that the same shortcuts that you took to release features quickly are now slowing you down. You can not scale and add new features on top of it, even if you do, they become quite unstable. In this situation you might want to take a step back and revamp/refactor you base system.

One of the easiest things that you can do to avoid this situation is follow coding guidelines.

Coding Standards

Well, what according to you is a good code? The simple definition could be: if it can’t be understood, maintained and extended by other developers then its definitely not a good code. The computer doesn’t care whether your code is readable. It’s better at reading binary machine instructions than it is at reading high-level-language statements. You write readable code because it helps other developers to read your code.

Naming conventions:

As the name suggests, it is a simple concept where you follow a specific naming conventions across teams. This becomes important when your team is growing and are solving problems on daily basis and pushing a lot of code every day.

This helps a lot when your team becomes big and a lot of developers are working on the same code-base. If you follow some fixed patterns while defining classes/functions/variables names, it becomes really easy for fellow colleagues to understand your code. This directly impacts delivery time taken by a developer to build/modify a feature on top of existing code. For example, let us suppose you want to define a time-stamp field in a database table, how would you name it ? If you have a fixed pattern like a “action_ts” or “action_at” for giving names then you can easily guess what could be the field name in the schema. If its a created time-stamp then it could be either “created_at” or “created_ts”. You do not have to go and check every-time you writing any logic over different database tables.

Function/Module/API writing (Size and Purpose)

Simplicity and readability counts. It’s always better to write to concise code than a messier one so that if any other developer is also looking at it who has no idea, should get what exactly it is doing. Not more than max 10–15 lines. Jenkins is considered as one of the greatest implementations, and has average function length of 2 lines.

A function/module should only do ONE thing and should do it NICELY. By following this, code becomes modular and it helps a lot in debugging. You can solve the problem better and debug faster when you know where exactly it’s coming.

When you are developing features over an established products, more than 50% times, new requirements are of the nature which you can build on top of existing code. In such cases, you can ship those requirements really faster and stable if existing code-base is modular and stable. Writing library functions a savior. There are countless advantages of writing a library code. It avoids code repetition, no surprises when it comes to response formats and of-course code re-usability.

Exception/Error Handling

Unknown errors are real pain in developers life. It’s always better if you know probable exceptions and errors in code in advance. But that is not the case always. Irrespective of all this, you definitely do not want your end-users to see unexpected errors on their screens.

When you have different micro-services and bigger development teams, if you follow standard response formats for across APIs and standard exceptions then there will not be any surprises in production. You can agree upon one format across all the services. Every API can have certain ‘response_data’ and standard set of error-codes. Every Exception will have an error-code and a message. Message could have variation viz, tech specific message and user facing message.

Writing test cases:

If you want to have a good night sleep, then you better have thorough test cases covering almost all aspects of your code. The best way forward with building test cases is at requirement stage only. Whenever a requirement comes, products managers discuss it with developers as well as QA. Both teams start preparing for possible use-cases and test-cases.

A testing unit should focus on one tiny bit of functionality and prove it correct. Each test unit must be fully independent. Each test must be able to run alone, and also within the test suite, regardless of the order that they are called. The implication of this rule is that each test must be loaded with a fresh data-set and may have to do some cleanup afterwards.

Automation plays an important role here. What else is needed for stable product where you have all test cases covered and running at intervals automatically, giving you a report of the all functionalities. Also, whenever you are adding/modifying code, you make sure either you write new test cases or modify existing ones.

Code Reviews:

This one thing save lives, trust me! Every team can benefit from code reviews regardless of development methodology. Initially it takes time if you do not have a procedure setup of doing code reviews, but eventually it becomes a habit. Code review should be one of the core development steps.

Code review generally is about:

• Does the new code conform to existing style guidelines?
• Does the written piece of code covers all the use-cases specified in the requirements and has relevant test cases written ?
• Are the new automated tests sufficient for the new code? Do existing automated tests need to be rewritten to account for changes in the code?

There are several advantages of this process such as -

Code reviews make for better estimates: Estimation is a team exercise, and the team makes better estimates as product knowledge is spread across the team. As new features are added to the existing code, the original developer can provide good feedback and estimation. In addition, any code reviewer is also exposed to the complexity, known issues, and concerns of that area of the code base. The code reviewer, then, shares in the knowledge of the original developer of that part of the code base.

Code reviews mentor new joiners: Code reviews help facilitate conversations about the code base between team members. During these conversations, team members share their views and new alternatives of doing things.

Code reviews take time: It’s an incremental process, where it takes time initially but as your code-base grows, it ensures, you are always pushing verified and tested code.

Hidden truth about code reviews: When developers know their code will be reviewed by a teammate, they make an extra effort to ensure that all tests are passing and the code is as well-designed as they can make it so the review will go smoothly. That mindfulness also tends to make the coding process itself go smoother and, ultimately, faster.

As a fast growing company our self, these set of guidelines have helped us a lot in shipping stable features on time and helping to increase a healthy learning environment.