A few years ago, I read Robert Martin’s clean code and as a new entrant to the software industry, it was one of the best introductory guides that I could ask for. There are several principles noted in the book that made a whole lot more sense when I saw poorly written production code dragging down the rest of the application with it.
While Salesforce has inbuilt provisions and safeguards in place to prevent bad code from executing on its servers in the form of governor limits, it is still not enough to uphold code quality. Of course, the reasons for badly written code going to production orgs are many and this article does not intend to dissect those. Codebases that are not compliant with clean code principles become harder to read, painful to maintain and the time needed to deliver a change request increases as complexity builds.
The principles noted in Robert Martin’s book are platform agnostic, but there are learnings that are certainly applicable to Salesforce development. So, if we were combine a few thoughts from that book along with principles that Salesforce themselves define in their developer documentation, it builds this neat little pocket guide for handy reference.
These principles are only but a subset of the overall set of clean code principles. This guide does not intend to be comprehensive or fully objective.
I have encouraged teams that I lead or have been part of to incorporate the following principles as much as possible:
- Bare minimum essentials:
- Remove debug statements from the code after a particular feature has been developed and tested.
- Ensure that code is always formatted before submitting it for review and approval to the team lead. Presentation matters.
- Do not write single line comments that try to explain the ‘what’, focus on better naming instead. Method headers and class headers are ok.
- Do not write logic that is not necessary.
- Stale code, if left untouched is a tech debt that slowly eats away at the readability of your codebase. Ensure that commented out code blocks are not deployed to higher orgs.
- Naming:
- All and any metadata must begin with the prefix tied to a project and business domain. Names which are based on the current business domain and provide business context are much preferred.
- Class names must be a noun and reflect the encapsulated logic.
- Method names must be an action or a verb.
- Variable names must not be of a single character. Use domain specific naming which explains the underlying data. Variables that are named ‘i’ and ‘j’ are probably okay to help with iteration of collections but descriptive names are better.
- Code construction:
- Classes must be small. Size of classes must not exceed 500 lines. Exceptions apply.
- Methods must be smaller. Size of methods must not exceed 40 lines. Exceptions do not apply.
- A method must do one thing and one thing only. The name of the method should reflect the logic within the method. Therefore, the smaller and shorter a method the more chances there are that the method is running only a specific piece of logic and is easy to read and maintain.
- A class must execute only one logical flow and must be named accordingly. If there is a deviation in the flow, it must be siphoned off to a new class with its appropriate naming and methods.
- For data structures, similar to classes and methods, we usually want to avoid names which are vague. Having names which clearly reflect the contained data is much preferred.
- Control structures: Nested for loops and nested while loops are highly discouraged unless there is no other option. Using collections like Maps are better than a nested loop.
- Method arguments: Zero arguments should be preferred. Ok, just one. Fine… two arguments is the limit. Maybe three. If you need more than three, you’re doing too many things within a single method. Please refer to the second and third points in this section to break it into smaller chunks.
- Avoid heavy coupling within code. Use dependency injection (to be covered in a later blog post) if possible.
- Exception handling:
- Use try – catch blocks. Don’t let exceptions go unhandled.
- Throwing custom exceptions is always encouraged. If the expected flow of control goes off the rails, throw a custom exception, let everyone know.
- Both system and custom exceptions must always be caught and then logged into an exception log object.
- When lightning components are involved, an exception must be caught and a user friendly message must be shown on the UI.
- Code re-use, configurability and maintainability:
- Custom labels and custom settings/metadata types are our friends and we like them. Use them to keep your application flexible. Don’t forget to name them with right business domain prefix.
- All the strings which will appear on a UI (field names, field labels, text labels etc) must be moved into custom labels. No hardcoding should be allowed.
- Hardcoding of configurable attributes should not be allowed within Apex or Aura. Use custom settings or custom metadata types to store and re-use configurations.
- Logic that is common to two or more methods must be moved into a single generic method. A Util class could potentially hold all such commonly used logic. Duplication of logic across the application must be avoided at all costs.
- Unit testing:
- All apex classes must have a test class associated to it with a minimum coverage of 90%.
- Unit tests must be written for positive scenarios and negative scenarios. A unit test must always cover a particular flow in the code and must not be written just to cover the lines and attain code coverage. (This happens quite often in time constrained projects.)
- Every positive unit test must have an accompanying negative test.
- Usage of Test data setup utility classes must be highly encouraged.
What are your thoughts on the principles suggested in this blog post? Let me know in the comments.
References: 1. Clean Code by Robert Cecil Martin. 2. Apex Developer Guide at developer.salesforce.com. Image credit: Photo by Oskar Yildiz on Unsplash.