The Art Of Readable Code by Dustin Boswell and Trevor Foucher
After reading it I have to say that it’s really good. Again, an incredible book for beginners something everybody should read between their first and second year programming. Really well written, no clutter, funny cartoons. Really good book.
Code should be easy to understand. AND
Code should be written to minimize the time it would take for someone else to understand it.
These are the two main mantras in the book. I would even say one mantra. The idea that you write code for some other person to read is great. They also say: “Maybe that person is you in 6 months”. And I agree. I noticed this in the beginning of my ‘career’ (for a lack of a better word). I looked at code I’ve written 6 months before and had problems understanding it. Today, I can look at code I’ve written 3 years ago and have not many problems understanding it.
Use a thesaurus
Because English is my second language I often do this while searching for better names. But I think even for native speakers there’s a payoff. I try not to make it too non-obvious, though.
Append important information to variable names. e.g. delay_ms, unsafe_user_comment, textfield_utf8, etc.
I like this idea and it’s extremely valuable in non-static typed languages. Which makes me think whether you should, for example, define two types of input. Save and Unsafe text. You write all your ‘internal’ function only using save text and therefore have to check your unsafe text you’re getting from the user / input.
Names should be non-ambigious
Comments as “director commentary”
Love this. If there’s something non-obvious describe it. If you tried a few things describe it. Really good advice.
Examples in the comments / docstring
I love when library writers do this. Python has a great implementation which allows you to define examples and tests in the docstring. But nonetheless, something worthwhile.
All in all, really good! I knew most of the stuff thanks to
- functional programming (bottom up, dreaming about what you want to do, no side-effects, )
- edw519 who said that naming is one of the most undervalued activities in programming. His comments got me started to use clean and consistent naming.
- my own laziness (writing as little code as possible)
I would recommend it to new comers, i.e. with about 2 years of experience. They will probably get the highest payoff. Absolute recommendation!