Code shouldn’t be clever, it should be readable

Styles and Conventions

Conventions, style guides or best practices came up naturally as more people collaborated in the same project. If everyone coded in their own unique way, it would be very cumbersome to work on someone else’s section.

To improve readability and maintainability, a development team should have agreed upon conventions for their source code. This will help any member of the team, new or otherwise, to more easily work in another part of the project even if they were not involved in that part. Conventions are language specific, so if a project has code in different languages, multiple conventions should be in play.

How can we make this agreement better?  

We can do a couple of things to make sure that the convention is being followed. For starters, these rules need to be written down in a wiki or somewhere accessible for everyone to consult. This way the team knows exactly what should be followed. Even if the convention being followed is the one used at Microsoft or Google, it should be referenced internally.

Secondly, having a configuration file that can be imported into the IDE will help a lot. This ensures that all developers have the style and will make it very easy to follow, just trigger the “format” option on the IDE and should move things around to be consistent. An example of settings: 

• Spaces or tabs (spaces rule, tabs drool!)
• Indentation depth for tabs
• Indentation styles
• Comment styles
• PascalCase vs camelCase
• Should private members start with an underscore?
• And more

Next, during the code review process code style should be part of the criteria that is considered. I understand that this part is difficult especially when there is a time crunch to get a hotfix out or when a project is hitting its deadline, but a clear review criteria will help.

Clever Code

All this works great for formatting and having consistent code throughout the project, but sometimes that is not enough. A developer can take shortcuts or use language features that while still following the agreed convention it’s still not readable. I’ll mention a few examples, but of course there are a lot scenarios where this pops up

• Ternary operators are great, they can make an if statement assignment quick and clear, however chaining ternary operators quickly make it confusing.
  

• Having too many inline conditions in an if statement. This one can have a performance impact, since if statements can “shortcut” once something is false, it can skip processing the next conditionals, so maybe a function can help make the code more readable.

• Don’t get me started on LINQ chaining.

Where to draw the line?

This is an interesting question. What some people call readable, others call bad code. A common example (in C#)  of this is using var keyword instead of the explicit type. 

For any confusion like this we can go back to our style guide, but if it’s not there a new rule should be added. The style guide should evolve as the project grows.

Conclusion

1. Have an agreed style guide per language and be open to update it as new scenarios arrive
2. Create a settings file to import into the IDE
3. Integrate style guide criteria in the code review process
4. Avoid clever code, but remember that different people have different definitions of what is readable