So I’ve finished one of the books I wanted to read this year. Much of the content of the book itself will be familiar to most developers with one or two years of experience developing applications, but there are still great tips here that can easily be overlooked.
As the title of the book suggests – the book is a compilation of tips based on experience on what makes code clean, how to identify and write clean code.
The book covered everything to do with keeping your code clean and testable. Ultimately, it tries to get you into a mindset of thinking how you write your code rather than just churning out hundreds of lines of code. The book really opens your mind up to question the way you write code a bit more – to communicate your thoughts a bit better to yourself and to others, to question why you’re doing things the way you do rather than just doing it because it works.
The book is well written, it reads very much like The Pragmatic Programmer whereby each chapter talks about a particular topic and the topic is divided into ideas and solutions.
I recommend the book highly to anyone – it’s one of those classic books that you can keep in your bookshelf and revisit every now and then.
What I gathered from the book
These should be familiar to you if you have a bit of programming experience, but although they are well known, some of them are quite easy to overlook.
You are allowed start with sloppy code
Yes, that’s right, it’s OK to write sloppy code, in fact, writing something that is non-trivial is better to be written quickly to begin with, otherwise, you will waste too much time trying to write well structured code during your first try. Think of it as writing your first draft, it’s OK to have some mistakes and not have a good structure.
Writing your initial code quickly gives you some time to review what exactly you are trying to do – the quicker you get started, the quicker you will see the challenges writing the particular method you are trying to write – this gets you thinking about the solution to the problem rather than the code you are trying to produce.
After writing your initial code, don’t forget to refactor before commuting it to your team’s repository – it is your responsibility as a professional to get your code to a good standard.
Not everything has to follow Object-Oriented approach
Objected-Oriented approach isn’t the universally correct approach – infact, procedural approach is sometimes what you want – let’s say you create some calculable type that returns some form of measurement or a weighing. In OO approach, you would probably have a base type, and each object type would have an implementation of a method to return it’s weighing – now, if I try to introduce a new method that is unique to each, I would have to implement it for every single type. In procedural approach, I would have each type as a simple data structure – and I would have a simple function that takes any of these data structures and return the weighing needed – if I want to introduce a new function, I would simply write that function once and it will encompass all of the types I have. In conclusion, it is easier to introduce new types with OO, and easier to add new behaviour with procedural approach.
Refer to p93-97 to read more about this.
Make good use of Abstraction or none at all
No abstraction is better than abstraction that is poorly defined – within the context of software programming, what exactly is abstraction? how should it be used? Abstraction is a way to hide away implementation details, telling the programmer “this is what it does” rather than “this is how it does it” abstracting away complexity of the implementation. For example, if you had an interface or an abstract class that had methods HeightInCm and HeightInInch, then you are still showing details that are not necessary – the general solution to this is to simply stick with one unit throughout the application and use a converter.
Put some thought into naming
When writing code – having to look at documentation every time you’re trying to use a function drains productivity. Working out what a variable is used for without any suggestion by its name also wastes a lot of time.
Some tips from Uncle Bob for naming:
Classes should usually be named as a noun and method names as verb.
Keep concept names consistent i.e. MyFactory.createObject() and MyFactory.makeObject(), either use create or make – never use both.
Avoid using names that imply a particular behaviour to developers i.e. ContactList implies a List behaviour as a class or if used as a local member – implies that it is a type of List<Contact>. – put simply, think of what the name implies.
Use computer science terms for naming if it makes sense and does what it implies i.e. ModalFactory, QueryBuilder, AccountVisitor, Type1ToType2Adapter, HtmlParser, JobQueue etc.
Use common coding style
You want your code to be consistent throughout – this makes your code easier to read as you know the typical style to expect.
Keep functions short
Don’t make it hard on your brain by making monstrously huge functions that do a lot of things. Keep it as simple and as easy to understand as possible.
Functions should not have unexpected side effects
Calling session.GetUser() should not try to log me into the system by trying some funky things and changing the current session, it should just do as it implies by its name alone.
Remove redundant code
Don’t just comment out redundant code, remove them. Your team and your future self will thank you later.
Prefixes and Hungarians notation are just noise
It’s the modern times – we have no use for these conventions any more, they are a distraction at best and just makes names longer in character count.
Comments
Comments in code is a code smell, code must be self documenting. Documentation can go out of date and eventually become irrelevant, but code that is clean and easy to understand will stand the test of time.
If there is anything out of the ordinary happening within your code i.e. hacky solution for good reason, then place a comment as to why the particular lines exist.
Each comment must make itself useful and not just add noise to your code – by noise, I mean comments like “we are incrementing by 1” or “assign to variable”
