Got the idea from here, but concepts below come mostly from horizontal reading and Uncle Bobâs speeches.
Overview
As a general rule of thumb, try to make your code âprettyâ.
Look at the indentations, do they make sense? Are you like five indentation levels deep? Is the naming descriptive? Is there a more efficient way to achieve the same thing? Is your code elegant?
Do you actually feel proud about it and have an urge to show it to your peers?
Made to be read
You got your code to work? Great!
That means itâs machine friendly. Now you need to go back and make it human friendly.
When coming up with new ideas or solutions to existing problems, our minds tend to become a bit messy.
We forget stuff, rush through ideas and generally donât care much for the âproper solutionâ but focus on âa solutionâ.
This is good, we should focus on getting the job done first.
But we also need to take some time after the fact to clean after ourselves.
You are most likely not the only one working on that peace of code, treat it like a common space.
First make it work, then clean it up.
Youâre not done when it works, Youâre done when itâs right.
â Robert C. Martin
Code is clean if it can be understood easily by a competent reader.
Another developer should be able to enhance it (or fix it for that matter).
Surprises might be nice irl but Iâm not looking forward to going âWTF?â when reading your code.
The more predictable the better.
Clean code does one thing well.
â Bjarne Stroustrup
Some Rules
General
- Conventions are there for a reason. Itâs easier for me to understand you if we both follow a set of common rules.
- KISS (Keep it simple stupid). Reduce complexity as much as possible, keep it minimalistic.
- Always find the root cause. Donât just fix the problem, actually fully resolve the issue.
- Boy Scout Rule. Leave the code better than you found it.
- Unix philosophy. Do one thing and do it well, donât write code with excessive/diverse responsibilities.
Understandability
- Be consistent. If class A has a
var name
and avar surname
, class B shouldnât have avar firsName
and avar lastName
in their place. - Use explanatory variables names. They help with semantics.
- Prefer value objects to primitive type. They also help with semantics.
- Avoid negative conditionals and be generally careful with conditionals, they get out of hand fast.
Naming
- They should be descriptive, unambiguous, meaningful, pronounceable and searchable.
- Donât use
data
orobject
in the name. We already know. - No Magic Numbers.
Functions
- They should be small and single scoped.
- Their names should describe their intent. Default to using verbs if possible.
- No more than 3 arguments, the fewer, the better.
- Side effects are usually bad, hard to track and easy to avoid.
- Donât use flag arguments. If a function does one thing or another based on the input, you should have two functions, not one.
Comments
- A necessary evil. To be avoided if possible.
- Trust your VCS, remove the code.
- Use them to: explain the intent, clarify the code or warn of consequences.
Structure
- Prefer vertical coupling/cohesion rather than horizontal.
- Group variables, objects and functions if they relate in usage.
- Respect indentation.
- Keep lines short.
- Blank lines can be used to separate weakly related elements. Consider separating them further.
Objects
- Expose an interface (API), hide internal structure.
- Keep them small and single scoped.
- Few imports and few instance variables.
Avoid
- Rigid software is hard to change, and there are usually cascading consequences for each change.
- Fragile code breaks in many places due to a single change.
- Complexity is sometimes necessary, but often accidental. Avoid the latter.
- Code Repetition is a pain to work with.
- Opacity is not a sign of a clever mind, but of an uncaring personality.