Clean code tips for beginners

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.


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!