Steps to better code

Isaac Lyman on July 28, 2017

This is an early version of a chapter from Your First Year in Code, a book of practical how-to and advice for new developers. If you're considering... [Read Full]
markdown guide

To those who want to learn more, remember that all of this is based on one important principle:

"Programs must be written for people to read, and only incidentally for machines to execute." -Harold Abelson, Structure and Interpretation of Computer Programs

The less reading someone has to do to completely understand how a block of code works, the better your code is. Full stop.

Yes, the code technically has to work. But a large part of the company you work for is already dedicated to that. QA, product owners, bug tracking systems, junior devs--there are plenty of people thinking about whether your code works. That will take care of itself. But probably the only person thinking about the readability of your code is yourself.

All eight of the rules I've described are aimed at making your code blocks short, expressive, and easy to understand ("easy to delete" is a variant of this). But you'd get by just fine if you approached each block of code (and the program itself) in terms of its grokability. Remember that your audience is not the compiler/interpreter/browser--your audience is a junior dev with a short attention span. Keep things short, explicit and to the point.


Nice article.

Your definition of refactoring is a bit loose in my opinion, do note that it refers to a very specific and well defined set of techniques, not just cleaning code. I do however understand that you do not want to write an article on refactoring, the term has unfortunately been overloaded.

"Code Complete" is a good book, I have both first and second edition. Currently reading "Clean Code", which are recommended by many, it is packed with good advice and can be recommended, it has many of the same points you raise, it does however also weigh towards a certain programming style, which not might be everyones cup of tea. In addition the "Working Effectively with Legacy Code" is a another good recommendation.

Take care,



Nice post, I would add a few things:

  • declarative code: strive to write code which describes 'what', not 'how'. SQL and rules engines are examples of tools that help you write very declarative programs.
  • genericity: code is more reusable when it does not deal at all with specifics.
  • enforce separation of concerns by programming to abstractions, typically by using polymorphism (e.g interfaces)
  • code is not an asset, it's a liability.

Dude! This is a really good advice. I want more!

Deep nesting is a huge problem on my work. I always re-code and change the "if" exactly like you suggest


Definitely a well-worded explanation. Breaking something down into everyday terms is a great way to teach. I try to employ this type of teaching methodology no matter what I'm expressing.

I love this and hope to see more like this in the future.


Great post! I love the recipe analogy. I should get around to reading my copy of Code Complete one of these days...


Really awesome post Isaac! I must say Number 4 (Hiding complexity) is spot on & my favorite. The code is so much cleaner & really helps a lot with maintainability! :-)
Thanks for sharing your insights!


Nice article.

Especially agree with points regarding

  1. Separation of concerns
  2. Dry
  3. Unit testing

I really love to unit test my code, helps to me solve minor bugs in code.


Really good list, I loved the bit on ifhell. I really despise the TryCatchIfElseMess that people get stuck in. I've done it before. It makes for really ugly and hard to maintain code bases as they grow in complexity.


Great list for new programmers and reminders for experieneed ones. It is easy to take the quick route sometimes but it always makes maintenence harder later on. This is something I really try to stress with my students.


Great post. My first semester in college, I never understood why we had to follow so many conventions like this but now I really appreciate these principles.


I think you forgot to change this: See that trail of ")};" => "});" , by the way Thanks for sharing, it really helps.


Wow, good eye. I should have you proofread all my stuff. Thanks!


Never really knew about these rules, but I follow them often just because it just looks neat. Very great post man! Got anymore?


Great read Isaac. You covered all of things I look for in solid developers. I think we can all gain from keeping this bookmarked for later.

code of conduct - report abuse