Making Good Software

A blog by Alberto G (Alberto Gutierrez)

Written by Alberto G

June 4th, 2009 at 11:29 pm

10 commandments for creating good code

with 48 comments

1.- DRY: Don’t repeat yourself.

DRY is usually the easiest principle to understand, but it is quite harder to apply. It means that when finding similar code in two or more places, we should abstract them into a new method and change the previous code fragments so they will now call the new method with the appropriate parameters.

DRY is maybe the most universal coding principle, I have never found a developer who would argue that repeating code is good, but, I have found developers that forget about this principle when coding unit tests, as an example: imagine that you have changed the interface of a class which had lots of unit tests, if you haven’t used DRY, you will have to manually change the call to this class interface to match the new signatures to each test case.

2.- Write short methods.


There are three very good reasons for writing short methods.

  1. Your code will be easier to read.
  2. Your code will be easier to reuse (short methods are likely to produce loose coupling).
  3. Your code will be easier to test.

3.- Use good names for your classes, methods and variables.

There is nothing nicer than using some other developer code and not having to read its documentation because the names of the classes and the methods are telling us everything, so, make everyone’s life easier and take this approach, expend always a few seconds before naming any element in your code.

4.- Assign the right responsibility to each class.

One class, one responsibility, that will sound familiar to those who know about the SOLID principles, but not any responsibility, the right responsibility, so if we have the class Customer, we won’t assign to it the responsibility to create a new sales action, we will just assign it the responsibility to handle all the data related with a customer.

5.- Keep your code organized.

This organization is at two levels.

  • Physical organization: Whatever the structure you are using, packages, namespaces, folders… Organize your classes in such a way that is easy and intuitive to find where the code is stored.
  • Logical organization: Whatever belongs logically together should have access to each other members, but what belongs to a different logic structure has to access them by an interface. These logic groups are commonly implemented as layers, services…

6.- Create lots of unit tests.

The most tests you have, the better, they are our safety net for all the changes we will have to perform in the code in the future.

7.- Refactor often and sooner.

Software development is a continuous discovery process, in order to keep up to date with good code that matches the new/changing requirements is essential to refactor the code as we go. As this is a risky task there are 2 main preconditions to avoid entering new bugs into the system.

  1. Have lots of unit tests.
  2. Do small refactor steps at a time. In software development there are very few things more annoying than start refactoring 2000 lines of code to after 3 hours of work realize that is necessary to roll back to the original version because now nothing works and the track of which change is causing the problem is lost.

8.- Comments are evil.

This particular one is a bit controversial, most of us were taught that comments are good, and actually it’s better to have a comment in an obscure piece of code than just having the code by itself, what this point means is that: even better than having a comment for an obscure piece of code is to not to have that code at all, just refactor it until is a nice and readable piece of code. [EDIT] Please read this other post for a better explanation of what “comments are evil” means.

9.- Code to an interface, not to an implementation.

This is a classic one, coding to an interface will free us from the implementation details, we just define a contract and rely on calling the defined operations on the contract, expecting that the actual implementation will be passed to our code or decided at runtime.

10.- Have code reviews.

We all make mistakes, and there’s nothing better than asking some other person to have a quick and informal review in our code to find them, in order to make the reviews,  it’s better not to wait until the code is completed, it’s better to ask for reviews whenever some important part of the code has been completed or when a few days have passed from the previous review.

48 Responses to '10 commandments for creating good code'

Subscribe to comments with RSS or TrackBack to '10 commandments for creating good code'.

  1. Completely agree on the content.

    But I like to have comments along with my code. Because, some business logic can not be fully expressed using code alone. :)

    veerasundark

    5 Jun 09 at 5:06 pm

  2. I’ll suggest commandment #11 : Tell don’t ask. Tell the object what to do. Don’t ask for its internal value.

    @veerasundark : If the business logic is correctly named (see commandment #3) you shouldn’t need comments.

    Julien Grenier

    5 Jun 09 at 6:26 pm

  3. Hrm. Unsurprisingly, I want to contribute with a tiny objection to #8.

    In general, I agree that clear code should be preferred over unnecessary comments, but often the choice is between a simple and suboptimal solution, or a complex and non-obvious solution. The complex solution may well be the right one, and it’s certainly not always possible to “just” refactor your way out of complexity. Refactoring should be a tool to manage complexity, not to reduce it.

    Which is not to contradict your point, I just think it’s wrong to think that refactoring is the solution to all troubles, and especially in complex situations, it should be applied with much care.

    One thing code cannot communicate is _why_. This is the reason we need comments. Code only tells you how, never why. If you want to be able to refactor your code efficiently, you really need those (hopefully not too many) comments to see what the intention of the code is.

    Simon

    6 Jun 09 at 12:37 am

  4. [...] commandments for creating good code 10 commandments for creating good code « Making Good Software Good guidelines, succintly put. (via [...]

  5. @Julien

    That’s great when you are working with your own objects, but not really possible when you are extending existing objects by overriding the parent’s functions.

    Example: you are extending a view method on an object in a standard web framework. The function name is the same as the parent, and it says nothing about what specific behavior you are adding in the override. A brief line explaining what functionality you are adding is appropriate.

    But totally agree otherwise.

    Teilo

    6 Jun 09 at 3:45 am

  6. @veerasundark:
    “Real Programmers don’t need comments– the code is obvious.”
    http://www.pbm.com/~lindahl/real.programmers.html

    just joking =]

    Rodrigo Lopes

    6 Jun 09 at 4:20 am

  7. There’s just no way that the code can explain general assumptions or timings required between components in a big system without using comments.

    Valentino

    6 Jun 09 at 5:15 am

  8. Great Article!

    Commandment #0 should be to *think* before you code.
    The saddest part is – most of the developers *think while coding*, and the obvious result is really bad code!!

    manjax23

    6 Jun 09 at 7:17 am

  9. [...] 10 commandments for creating good code « Making Good Software (tags: code development programming tips) [...]

  10. [...] Theory by Alberto G on June 6, 2009 I have recently published an article called “10 commandments for creating good code“, in which the commandment number 8 says “Comments are evil”, well, as I was [...]

  11. [...] This post was Twitted by rubypractices – Real-url.org [...]

  12. Hey, we shouldn’t be posting here – comments are evil, remember

    philsquared

    6 Jun 09 at 1:47 pm

  13. 10 commandments for creating good code « Making Good Software…

    Thank you for submitting this cool story – Trackback from DotNetShoutout…

    DotNetShoutout

    6 Jun 09 at 1:50 pm

  14. Those assumptions not easily explained in code are easily explained in tests. You do have tests for your assumptions, don’t you?

    Tripp

    6 Jun 09 at 2:50 pm

  15. I’m not quite so sure about the regular refactoring part. I tend to spend more time on up-front design specifically so that I don’t have to refactor multiple times. In fact, once I’ve written a piece of code I don’t really refactor until I’m writing client code and think of something that needs to change to make the interface simpler. In other words, I refactor on a need-to basis as opposed to often and sooner.

    Basu

    6 Jun 09 at 3:44 pm

  16. I feel your understanding of DRY principle is not correct. From http://www.artima.com/intv/dry.html,

    “Most people take DRY to mean you shouldn’t duplicate code. That’s not its intention. The idea behind DRY is far grander than that.

    DRY says that every piece of system knowledge should have one authoritative, unambiguous representation. Every piece of knowledge in the development of something should have a single representation. A system’s knowledge is far broader than just its code. It refers to database schemas, test plans, the build system, even documentation.”

    vishalsodani

    6 Jun 09 at 4:02 pm

  17. Of course I have tests. So what you are suggesting, instead of reading 4-5 lines of comments explaining the general logic, the reasons why the logic was implemented in a specific way and the assumptions behind some code, is to go read other code that has a different set of assumptions. I call this being a lazy programmer :) . Comments are part of the code, if you don’t change them with the code you shouldn’t even bother committing the patch.

    The only comments that code does not need are those that rephrase what the code is doing and those are also the only ones that are actually not needed because you can already see what the code is doing, as you say.

    Valentino

    6 Jun 09 at 4:16 pm

  18. [...] 10 commandments for creating good code « Making Good Softwaremakinggoodsoftware.com [...]

  19. I’ve written about this a few months ago, including one post on how comments tend to deteriorate. I found it particularly interesting that in one example claiming to demonstrate good commenting, the comment was ALREADY misleading in the first place, even before the code has had a chance to get out of sync with the comment (http://blog.agilephp.com/2009/01/04/how-code-comments-deteriorate/)

  20. [...] out.  Start by looking at the author’s “10 commandments for creating good code” http://makinggoodsoftware.com/2009/06/04/10-commandments-for-creating-good-code/ and then check out some of his other [...]

  21. I strongly disagree with your idea of refactoring.
    When I find code that is more complicated than necessary, and it needs to be touched anyway e.g. because of bugs, I will try to force simplicity onto that code by all means.
    Of course it strongly depends on the quality of that code and that quality varies widely where I work, in Free Software.

    Andreas

    6 Jun 09 at 7:20 pm

  22. [...] articolul de aici, am realizat că mai sunt multe de schibmat în anumite moduri de a scrie codul. Nu e necesar doar [...]

  23. [...] This post was Twitted by netcrema – Real-url.org [...]

  24. This formulation as “knowledge” is better than the DRY principle in the article. DRY doesn’t necessarily apply to code only or duplicating code … but also to Data. Constants/enums. Configuration. Wiring up collections of objects. I prefer to think of the Single Point of Truth (SPOT) of facets in the system.

    jsled

    6 Jun 09 at 11:24 pm

  25. [...] 10 commandments for creating good code 1.- DRY: Don’t repeat yourself. DRY is usually the easiest principle to understand, but it is quite harder to [...] [...]

  26. [...] 10 commandments for creating good code « Making Good Software [...]

  27. [...] 10 commandments for creating good code – Alberto Gutierrez offers his suggestions for 10 commandments for creating good code – these are mostly the conventional wisdoms, but often worth reminding ourselves (and others) of the importance of some of these rules [...]

  28. [...] Non sono proprio d’accordo su tutto … cmq penso che 8 su 10 siano davvero delle ottime regole da seguire con costanza: 10-commandments [...]

  29. [...] 10 commandments for creating good code at Making good software [...]

  30. [...] 10 Commandments for Creating Good Code: Alberto Gutierrez plays the Moses of coding and presents his commandments to all of the world wide web. [...]

  31. [...] activity will help you to see if the candidate has a good sense of what good code is and will help you to determine how good he is reading [...]

  32. Except for the “comments are evils”, which I think a good developper should be able to use correctly, this is a great post, and I’ll refer my co-worker to it!
    Thanks ;)

    Jef

    7 Aug 09 at 5:48 am

  33. [...] 10 commandments for creating good code Making good software (tags: programming) [...]

  34. [...] 10 commandments for creating good code [...]

  35. Hello Alberto, it’s a real pleasure to read your posts. I’ve translated this one : 10 commandements pour écrire un bon code. Regards, Fabrice.

    Fabrice Aimetti

    12 Aug 09 at 2:07 am

  36. and the most important one of all…

    http://www.life-nonprofit.org/m/developmenttips.jpg

    _mark

    13 Aug 09 at 4:08 pm

  37. [...] 10 commandments for creating good code | Making Good Software (tags: code bestpractices good bestof) [...]

  38. [...] aquí. Nota: esto NO es una traducción literal del post original. Sólo he seguido el mismo y más o [...]

  39. [...] 10 commandments for creating good code [...]

  40. Познавательно написано, но как говорится, для полноты информации нужно как минимум три источника :)

  41. [...] 10 Commandments for Creating Good Code [...]

  42. [...] not perfect, or even workable, as you move into code. This blog title makes reference to a blog by Alberto G – 10-Commandments-For-Creating-Good-Code, and is in answer to some comments that having the design done before you start was not one of [...]

  43. I love #8. In fact I wrote 5 Spanish articles about it (see http://blog.svpino.com/2010/12/comentarios-no-no-y-no.html).

    Comments? No, no, and no!

  44. Thanks for the information, very inspiring piece!

    Malik Picht

    3 May 11 at 2:18 am

  45. [...] 原文出自:Alberto Gutierrez [...]

  46. [...] 原文:Alberto Gutierrez 翻译:伯乐在线 敏捷翻译 – 唐尤华 程序开发 编程 2011.08.14 Android 上的 10 款 Web 开发应用工具»  [...]

  47. Very good, but, It would be nice with a couple of code examples.

    fred

    1 Feb 12 at 4:51 pm

Leave a Reply