Whether a beginner or an expert, it’s never too early or too late to improve your coding hygiene. Here are some clean code principles.
What is clean code?
Clean code can easily be read, understood, and enhanced by a developer other than its original author.
Clean code is a lot like good non-fiction writing, it’s concise, avoids repetition and conveys your message clearly.
Why Should You Write Clean Code?
When learning to code, you’ll most likely do several small projects on your own and then forget about them. That’s not how it works in the real world! Most code isn’t written and forgotten about, it is written and then modified over time to keep it current and efficient. Your code must be written so when you come back to it several months later, you understand it as well as you did when writing it.
Software development is all about teamwork. The best teammates are the ones who can communicate their ideas clearly. Diving into code that doesn’t have a clear direction is time-consuming for everyone. Your team need to be able to understand your code and discuss it so you can improve it.
If you think you spend most of your time writing code, you’re mistaken! You spend far more time reading code, debugging, identifying problems, and finding solutions. Clean code makes all these things easier. It’s a no-brainer!
The following are some basic clean code principles I gleaned from “Clean Code” By Robert C. Martin.
General Organisation
- Always follow the DRY principle — Don’t repeat yourself.
- Local variables should be declared as close to their usage as possible.
- Keep lines short, a good character limit on a line is 120 characters.
- Keep files short, no more than 1000 lines.
- Don’t break indentation.
Names
- Naming is the easiest thing you can improve but it has a huge impact.
- The names of classes, variables, and methods must be meaningful and clearly say what a method does or what an attribute is.
- Pronounceable names help others understand your code and communicate about it more easily.
- Use nouns for classes, packages, and variables.
- Use verbs for functions.
- Avoid acronyms and ambiguity, make names explicit.
Functions
- Functions should be small and do only one thing and do it well; this is called the separation of concerns principle.
- Less than two parameters are ideal, more than three is never a good idea. If you have several parameters, this is usually a sign that your function is doing too much and needs to be broken down.
- Avoid causing side effects; Do what the name suggests and nothing else.
- Don’t pass flags/booleans as arguments.
Comments
- Comments should be avoided; the code should speak for itself.
- Obvious comments just add noise.
- Don’t comment out code, be brave enough to remove it. Commented code can often become a relic which survives for years because no one has the courage to get rid of it.
- Use version control systems for handling code that is expired, deprecating, or experimental.
- Sometimes comments are useful to warn other programmers about the consequences of certain actions.
- Use comments to reveal extra information such as complex business logic, behaviours, assumptions, future suggestions etc.
Tests
- Only test a single concept per test and only have one assert per test. The more everything is separated, the easier it is to find issues.
- Unit tests should be written just before the production code that makes them pass. If you write tests after the production code, the production code may be hard to test.
- Writing good tests saves a lot of time in the future because it makes it very easy to identify problems when someone makes a breaking change.
Tests should follow FIRST principles:
- Fast
- Readable
- Independent
- Repeatable in any environment.
- Self-Validating — should have a Boolean output, tests either pass or fail.
- Timely
Errors
- Use exceptions instead of error codes at lower levels. Keep error codes for communication between different layers, and systems.
- Use Try/Catch blocks
- Create clear error messages to help maintainability. Don’t Return Null!
- If a third-party API is returning null, wrap the method with a method that either throws an exception or returns a special case object.
Conclusion
This blog has been a quick introduction to some clean code. I highly recommend reading the original book which goes into much more detail. The next step is to practice, practice and then practice some more. Your teammates will thank you for making their lives easier!
