Making Good Software

A blog by Alberto G (Alberto Gutierrez)

Written by Alberto Gutierrez

May 7th, 2009 at 5:00 pm

The pyramid of code quality, the 5 characteristics of good code.

with 18 comments

The quality of the code can be seen as pyramid where each of the 5 vertex are one characteristic of the code.

The pyramid has two parts the base, and the apex.

pyramid

The base of the pyramid will be formed by the characteristics that make the code robust, future-proof. The apex is represented by the amount of functionality and reliability of the code.

The higher you want your apex to be (more functionality and reliability) the bigger the base has to be.

The base of the pyramid

pyramid_basenames

Readability

This characteristic measures how easy is to read and understand the code and it’s purpose. The main factors that affect the readability are:

  • Good comments
  • Good naming of variables, functions, classes…
  • Consistent coding standards
  • Clean logic

The highest readability, the less time a new developer will need to understand what the current code is doing.

Extensibility

This characteristic measures how easy is to add new functionality, a good design will likely provide high extensibility. The highest extensibility, the less time for a developer to add new functionality as changes in the current code shouldn’t be necessary.

Atomicity

This characteristic measures how the different units of logic of the application are separated so that when a change is necessary it is only performed in one place in the current code. High atomicity is usually achieved following a few good principles when coding like:

  • SOLID Principles
  • DRY
  • Continuous refactoring

Testability

This characteristic measures how much automated and how much coverage the code tests have. This not only covers unit testing, but integration testing and E2E testing as well.

The apex of the pyramid

The apex of the pyramid measures how many things the code does, and how reliable it is.

Balancing the base and the apex.

The key for having a good pyramid is that the base is big enough for the required apex, in the next post we will discuss what different types of pyramid shapes we can find and which are adequate for every scenario, you can subscribe to get the second part of this article by following the RSS link on the top right hand side of the blog.

18 Responses to 'The pyramid of code quality, the 5 characteristics of good code.'

Subscribe to comments with RSS or TrackBack to 'The pyramid of code quality, the 5 characteristics of good code.'.

  1. Interesting. Now, writting software wich has a good length in the four base dimensions, on budget and on time, is hard. =)

    Arturo Tena

    7 May 09 at 8:28 pm

  2. Hi guys, let me apologize, as a reader has detected, the first pyramid was 1Mb, I have just changed it back to gif and now it´s only a few Kb.

    Also, I should give credit to the original source I took the pyramid from: http://commons.wikimedia.org/wiki/File:Pyramid.svg

    Alberto G

    7 May 09 at 10:14 pm

  3. [...] are one characteristic of the code. The pyramid has two parts the base, and the apex. pyramid [...]Windows 7 XP Mode Explained- It's Beta Software We've been as excited about the Windows 7 [...]

  4. I take issue with extensibility. Great code does one thing well. Being extensible without having an idea about what those extensions might be is just overengineering

    ben

    8 May 09 at 3:53 am

  5. great entry! i agree w/ you on each “base”. i once had to rewrite an application w/ at least 50,000 of codes with *none* of the readability suggestions you wrote about (save for a handful of vague comments). most horrible project ever.

    programatique

    8 May 09 at 3:05 pm

  6. [...] The pyramid of code quality, the 5 characteristics of good code. The quality of the code can be seen as pyramid where each of the 5 vertex are one characteristic of the code. The [...] [...]

  7. I’d add idempotency as another. I know it’s unavoidable in some cases, but it’s just a relief to when some code handles client mistakes gracefully.

    Ivan

    9 May 09 at 4:14 pm

  8. Hey, nice post.

    With regard to comments and readability:

    I work at a small agile start-up where we have finally decided that comments, in the general case, are evil. We’ve dubbed them “lies” and have each decided to more-or-less stop using them, because they get out of date and mislead people about the intentions of the code.

    We have decided that code should be made readable with its structure and naming, without comments.

    We do still use comments in cases where there really is no other way, but it is about 1 line of comments per few hundred lines of code.

    Jonathan Hartley

    10 May 09 at 1:00 am

  9. Hi Jonathan!

    I really admire the direction you are taking in your team, I have to admit that I was skeptic when I first heard about comments being evil, but after seen a few examples I have to admit that it really works.

    Alberto G

    10 May 09 at 11:25 am

  10. [...] on the previous article, we have seen that the code can be seen as pyramid where its base is formed by the characteristics that make the code robust and future-proof and the [...]

  11. Hey Alberto, thanks for the response. I really wonder about how best to discuss the comments thing. I’ve spent so many years so deeply knowing and feeling that ‘comments == good’, that it’s difficult now to wonder whether I was simply wrong all those years, or whether there are particular environments where it’s more true and others where it’s less true.

    I guess I am currently working in a place that is possibly a close-to-ideal sort of situation for abandoning comments. We are a small team (currently 7) with relatively high standards (everyone is smarter than me.) We pair program on almost everything and switch pairs every day, so we have all grown to know the entire project quite thoroughly. We seem to assimilate new-hires and interns quite quickly, so I think the code really is comprehensible without comments – not *just* that we’re all so familiar with it that we don’t need them.

    I think we are making the right decision for us, to abandon comments, but perhaps it would not be the right decision for other teams in other circumstances.

    Jonathan Hartley

    10 May 09 at 10:03 pm

  12. Very good diagram, illustrates what good software ‘is’. Are there any references for the pyramid?
    I immediately though of the book Clean code.

    twistedmind

    11 May 09 at 2:19 pm

  13. @ twistedmind: Thanks for your comment, actually the idea of the pyramid was an image I always had on my head to represent the code quality, I’ve never seen any previous reference… and about the book “Clean code” I have actually just ordered from amazon I’ve heard very good reviews about it, I’m looking forward to read it.

    Alberto G

    11 May 09 at 2:32 pm

  14. [...] care about your code quality, then improve the [...]

  15. [...] To be proud of the solution, it is not any solution, it is a good solution. It follows the principles of the “Pyramid of the software quality“. [...]

  16. [...] To be proud of the solution; it is not just any solution, it is a good solution. It follows the principles of the “Pyramid of the software quality“. [...]

  17. [...] care about your code quality, then improve the [...]

  18. [...] To be proud of the solution; it is not just any solution, it is a good solution. It follows the principles of the “Pyramid of the software quality“. [...]

Leave a Reply