What do you think?
Rate this book
Building Maintainable Software
Have you ever felt frustrated working with someone else's code? Difficult-to-maintain source code is a big problem in software development today, leading to costly delays and defects. Be part of the solution. With this practical book, you'll learn 10 easy-to-follow guidelines for delivering software that's easy to maintain and adapt. These guidelines have been derived from analyzing hundreds of real-world systems.
Written by consultants from the Software Improvement Group (SIG), this book provides clear and concise explanations, with advice for turning the guidelines into practice. Examples are written in Java, but this guide is equally useful for developers working in other programming languages.
10 Coding Guidelines
- Write short units of code: limit the length of methods and constructors
- Write simple units of code: limit the number of branch points per method
- Write code once, rather than risk copying buggy code
- Keep unit interfaces small by extracting parameters into objects
- Separate concerns to avoid building large classes
- Couple architecture components loosely
- Balance the number and size of top-level components in your code
- Keep your codebase as small as possible
- Automate tests for your codebase
- Write clean code, avoiding "code smells" that indicate deeper problems
Why you should read this book
Taken in isolation, the guidelines presented in this book are well-known. In fact, many well-known tools for code analysis check a number of the guidelines presented here. The following three characteristics set this book apart from other books on software development:
We have selected the ten most important guidelines from experience.
We teach how to comply with these ten guidelines.
We present statistics and examples from real-world systems.
This book is part our Training on Software Maintainability - and subsequent Certification on Quality Software Development program. For more information about this program, please contact training@sig.eu.
Written by consultants from the Software Improvement Group (SIG), this book provides clear and concise explanations, with advice for turning the guidelines into practice. Examples are written in Java, but this guide is equally useful for developers working in other programming languages.
10 Coding Guidelines
- Write short units of code: limit the length of methods and constructors
- Write simple units of code: limit the number of branch points per method
- Write code once, rather than risk copying buggy code
- Keep unit interfaces small by extracting parameters into objects
- Separate concerns to avoid building large classes
- Couple architecture components loosely
- Balance the number and size of top-level components in your code
- Keep your codebase as small as possible
- Automate tests for your codebase
- Write clean code, avoiding "code smells" that indicate deeper problems
Why you should read this book
Taken in isolation, the guidelines presented in this book are well-known. In fact, many well-known tools for code analysis check a number of the guidelines presented here. The following three characteristics set this book apart from other books on software development:
We have selected the ten most important guidelines from experience.
We teach how to comply with these ten guidelines.
We present statistics and examples from real-world systems.
This book is part our Training on Software Maintainability - and subsequent Certification on Quality Software Development program. For more information about this program, please contact training@sig.eu.
146 pages, Paperback
Published December 11, 2015
18 people are currently reading
161 people want to read
Ratings & Reviews
Friends & Following
Create a free account to discover what your friends think of this book!
Community Reviews
Displaying 1 - 22 of 22 reviews
May 9, 2018
I have read this book carefully twice. The presented guidelines may be exceedingly strict some times, but overall I found them very helpful while refactoring and I actually found myself implementing several of these good practices right away. I haven't read anything else on this particular subject, but I would easily recommend this book not only to juniors but to experienced developers as well.
Examples of exceedingly strict guidelines:
- What do they mean by "there is never a good reason for code comments"? What about "just for fun"?
- Studying the first rule of max 15-lines of code per unit, while staring at my 100-line methods, with a :o face.
- "Replace Conditional with Polymorphism pattern". Oh come on, what's wrong with plain simple switches?
- "Aim for at least 80% line coverage / as many lines of test code as production code". Lol, what?
Examples of exceedingly strict guidelines:
- What do they mean by "there is never a good reason for code comments"? What about "just for fun"?
- Studying the first rule of max 15-lines of code per unit, while staring at my 100-line methods, with a :o face.
- "Replace Conditional with Polymorphism pattern". Oh come on, what's wrong with plain simple switches?
- "Aim for at least 80% line coverage / as many lines of test code as production code". Lol, what?
February 25, 2023
Very helpful, even for a hobby software dev.
March 6, 2016
The 10 guidelines explained in this book can help you to massively improve the quality and maintainability of your code. Reading it is definitely time well spend. I hope the C# edition will be as good as the Java one.
October 2, 2017
Mostly deals with easy to measure things like number of lines of code in a method, number of branches, number of parameters and so on. It does not deal with design patterns or how to write good object-oriented software, which I believe is much more important and fundamental for software to become maintainable. The guidelines that the book cover is not bad or wrong, but they are not the key to writing maintainable future-proof code as the book claims. By following design patterns and not least, do soft activities such as communicating with domain experts, will make you much more successful in writing good software.
This book seriously suggest to create a class per country for describing the colors of the flag.
My impression is that the book is written by an academic but with no real programming experience or deep understanding of object-oriented programming. Also, this book is a rewrite from a Java edition, with some Java references still in it.
This book seriously suggest to create a class per country for describing the colors of the flag.
My impression is that the book is written by an academic but with no real programming experience or deep understanding of object-oriented programming. Also, this book is a rewrite from a Java edition, with some Java references still in it.
September 16, 2017
Опытный разработчик скорее всего уже знает и применяет все советы, которые представлены в этой книге. Реальный полезный объем книги можно было бы уместить на десяти страницах. Некоторые разделы книги мне показались странными (если не сказать бесполезными). Например в конце каждой главы представлены диаграммы соответствия метрикам для трех разных систем. Зачем они мне? Какой в них полезный смысл? Раздел доводов против полезных принципов видится весьма надуманным. Компетентный разработчик все и так это понимает и на свой шкуре уже скорее всего понял почему правильно делать так а не иначе. Да и само пояснение к полезным принципам разработки написано каким-то академическим языком. Как будто автор это писал то ли для курсача, то ли для диплома, то ли для научной работы.
March 30, 2018
Short overview for new programmers. It was written for those who came to the profession without an education in the field. Lists some common subjects like keeping units short, with examples in Java and rebuts common reasons people have no to eat their vegetables.
It doesn't really have much new to offer over classics in the field like Refactoring, Code Complete, Clean Code or The Pragmatic Programmer, but it's short and focused.
It doesn't really have much new to offer over classics in the field like Refactoring, Code Complete, Clean Code or The Pragmatic Programmer, but it's short and focused.
May 15, 2017
Good enoough. Examples based on real systems are awesome. But most part of book are just reusing of Martin Fowler's "Refactoring..." which is more robust i guess. So for those who read "Refactoring" i can't strongly recommend it
July 10, 2017
A recipe book with some glimpses of good advice, common sense and "we had data so we ran some analytics". Software quality is a more complicated topic than this (a disclaimer the authors readily make).
May 21, 2022
Clear reasoning and straightforward advice presented in a largely language-independent way. (I have never written a line of C# code in my life, and had no issues following the C# edition of this book.)
July 23, 2018
Вначале более менее полезные советы
А дальше больше теоретические умозаключения + реклама своей компаний
Более менее проходная книга
А дальше больше теоретические умозаключения + реклама своей компаний
Более менее проходная книга
September 3, 2020
A handful of hints and principles for dealing with codebases. Most are intuitive and make sense, but some are rather unrealistic.
March 17, 2017
A very good book that states in a simple 10-rule structure the great vision of software development.
March 11, 2017
This book was a nice review of many good software development practices found in other books, but I didn't really learn much new information despite this being published several years after some classics (Bob Martin's "Clean Code", Steve McConnell's "Code Complete", and Martin Fowler's "Refactoring: Improving the Design of Existing Code"). One thing that I did find interesting was seeing the statistics and details of how SIG actually quantifies code quality and correlates their metrics with success and failure rates in projects.
October 21, 2023
This short book offers an interesting model to quantify software maintainability using a Java codebase as example. The model is built on ten (10) generally accepted principles and SIG's (the author's parent organization) take on each to rank best-of-the-breed software. The principles, simplified here, and thresholds to be "4 stars" are, roughly,
1. Short methods -- at least half the methods to be 15 lines or less.
2. Methods with shorter "branching factor" (or Cyclomatic Complexity) -- at least 75% with 5 or less.
3. Code is not duplicated a lot -- at least 95% code is "non-redundant" (i.e., not copied elsewhere)
4. Methods have short "interfaces" (i.e., input params) -- at least 85% methods have at most 2 inputs.
5. Modules (i.e., classes) are loosely coupled -- at most 20% of classes have >10 incoming calls (fan in) aggregated over its methods.
6. Components (e.g., packages) are loosely coupled -- no more than 15% code residing in modules with incoming dependency.
7. Components are balanced in size and numbers -- equivalent of "Gini Coefficient" -- the metric used to compare income equality, 0.0 being perfectly egalitarian society, 1.0 being perfectly inequal -- ideally, about 9 components with inequality coefficient being 0.7
8. Small Codebase -- equivalent to 20 person-years to completely rebuild. This equates to about 175,000 lines of code in Java.
9. Testability - higher automation in tests -- interestingly, measured with combination of #2, #6 and #8 above - not with coverage. Hypothesis here is smaller codebase where packages are loosely coupled and methods/functions are not complex is easy to automate with tests. I agree with this - writing tests or automating tests is a 2nd order problem (much easier to fix) if the 1st order (code is testable) problem is solved. If not, the investment in automating is super-linear and ROI is low/negative.
10. Clean Code -- generally, without obvious "smells", e.g., good comments, no dead code (something that is not used!), no long names, no badly/unhandled exceptions.
This is a unique take on something we all grapple in real life. I really liked some insights - especially, earlier chapters illustrated, say, how to use "value object" to reduce a method's signature; or use fluent interface style in constructors to make code readable etc. I wholeheartedly agree with the author that measuring testability != measuring tests. That, from experience, has been a foundational flaw of most very senior level technology leadership. If we blindly try to fix lack of test coverage in a legacy codebase without evaluating its "testability" (e.g., volume, coupling and structure), it will be as if we are asking a senior member of society who has never lifted weight to deadlift 2x his bodyweight in 2 months! It will not only cause wasted efforts, but could do serious harm as well.
Like all models, squint at the specific model but rather at the framework of code maintainability to get most value from this lean book.
That said, important things with nuance are always observable but not readily measurable. Apart from noise and jitter associated with measuring a 10 year old codebase contributed by 400 engineers, maintainability is inherently a technology dimension. The other two principal axes are business- did/are we make a conscious trade-off, say, for growth; and people- most leaders are inherent optimists and they “frequently resent the need for maintenance and tend to resist doing it, instead preferring to live in the world of ideals rather than the drudgery of constant tasks."
The eleventh, and most important, pattern would be "To influence the real-life need of maintainability". But that is the essential key to successfully leading irrespective - either to build or to maintain!
1. Short methods -- at least half the methods to be 15 lines or less.
2. Methods with shorter "branching factor" (or Cyclomatic Complexity) -- at least 75% with 5 or less.
3. Code is not duplicated a lot -- at least 95% code is "non-redundant" (i.e., not copied elsewhere)
4. Methods have short "interfaces" (i.e., input params) -- at least 85% methods have at most 2 inputs.
5. Modules (i.e., classes) are loosely coupled -- at most 20% of classes have >10 incoming calls (fan in) aggregated over its methods.
6. Components (e.g., packages) are loosely coupled -- no more than 15% code residing in modules with incoming dependency.
7. Components are balanced in size and numbers -- equivalent of "Gini Coefficient" -- the metric used to compare income equality, 0.0 being perfectly egalitarian society, 1.0 being perfectly inequal -- ideally, about 9 components with inequality coefficient being 0.7
8. Small Codebase -- equivalent to 20 person-years to completely rebuild. This equates to about 175,000 lines of code in Java.
9. Testability - higher automation in tests -- interestingly, measured with combination of #2, #6 and #8 above - not with coverage. Hypothesis here is smaller codebase where packages are loosely coupled and methods/functions are not complex is easy to automate with tests. I agree with this - writing tests or automating tests is a 2nd order problem (much easier to fix) if the 1st order (code is testable) problem is solved. If not, the investment in automating is super-linear and ROI is low/negative.
10. Clean Code -- generally, without obvious "smells", e.g., good comments, no dead code (something that is not used!), no long names, no badly/unhandled exceptions.
This is a unique take on something we all grapple in real life. I really liked some insights - especially, earlier chapters illustrated, say, how to use "value object" to reduce a method's signature; or use fluent interface style in constructors to make code readable etc. I wholeheartedly agree with the author that measuring testability != measuring tests. That, from experience, has been a foundational flaw of most very senior level technology leadership. If we blindly try to fix lack of test coverage in a legacy codebase without evaluating its "testability" (e.g., volume, coupling and structure), it will be as if we are asking a senior member of society who has never lifted weight to deadlift 2x his bodyweight in 2 months! It will not only cause wasted efforts, but could do serious harm as well.
Like all models, squint at the specific model but rather at the framework of code maintainability to get most value from this lean book.
That said, important things with nuance are always observable but not readily measurable. Apart from noise and jitter associated with measuring a 10 year old codebase contributed by 400 engineers, maintainability is inherently a technology dimension. The other two principal axes are business- did/are we make a conscious trade-off, say, for growth; and people- most leaders are inherent optimists and they “frequently resent the need for maintenance and tend to resist doing it, instead preferring to live in the world of ideals rather than the drudgery of constant tasks."
The eleventh, and most important, pattern would be "To influence the real-life need of maintainability". But that is the essential key to successfully leading irrespective - either to build or to maintain!
February 10, 2016
Very good explanation on each of the points for future proofing the code. All of the points have already been covered in several software architecture books. Where this book stands out is , the motivation and the guidelines provided for each of the point. example.
Guideline 1: Writing short units of code. The book explains examples of how to refactor the code using extraction and other principles (explained in depth in Refactoring IT book by Martin Fowler) ..
Overall the book is a good summarizer for writing clean and maintainable code.
Guideline 1: Writing short units of code. The book explains examples of how to refactor the code using extraction and other principles (explained in depth in Refactoring IT book by Martin Fowler) ..
Overall the book is a good summarizer for writing clean and maintainable code.
January 9, 2017
If you're looking for a definitive reference this is not it... This is more like an introduction (cheatsheet / for dummies approach) to books like Uncle Bob's Clean Code or Fowler's Refactoring.
My rating comes mostly because it addresses such a relevant/complex topic with a simple (some would argue simplistic, but I' not sure I agree) approach that could impact our industry deeply if adopted in any meaningful way.
My rating comes mostly because it addresses such a relevant/complex topic with a simple (some would argue simplistic, but I' not sure I agree) approach that could impact our industry deeply if adopted in any meaningful way.
March 28, 2016
Nothing new comparing to famous Clean Code: A Handbook of Agile Software Craftsmanship. But for sure interesting position for those willing to understand SIG rating.
July 11, 2017
Nothing groundbreaking here. Just some common sense guidelines worth keeping in mind when you write code. 3.5 stars.
August 23, 2016
Ondanks het een redelijk hoog open-deur gehalte toch een erg leuk, vlot en vooral helder boek over software ontwikkeling.
October 15, 2016
i prefer clean code, is almost the same
April 8, 2018
Good book, a shorter version of clean code for Java developers
Read
April 27, 2019I went into this book hoping for some practical suggestions on how to write better code. I found a set of highly practical principles that initially shocked me.
Some of the suggestions here seem unbelievable at first glance, such as the very first guideline: Limit the length of code units to 15 lines of code. Yep, the authors want you to keep all your methods to 15 lines or less. This seemed crazy to me, but the authors proceed to defend their position quite ably. I then tried their advice on my current project, and lo and behold my code got cleaner, more logical, easier to extend, and easier to maintain.
I had similar reactions to other guidelines, like limiting code complexity within a code unit to 4 branch points and limiting function parameters to 4. I also had similar positive experiences from implementing them.
Other chapters are less revolutionary but still worth rigorous application: avoid copy-and-paste (instead genericize the code you're copying so that it applies to both use cases), write automated tests, and loosely couple components. You may have read of these things before, but the explanation and defense helps to settle them into the reader's mind and encourage him or her to practice them consistently.
Some of the suggestions here seem unbelievable at first glance, such as the very first guideline: Limit the length of code units to 15 lines of code. Yep, the authors want you to keep all your methods to 15 lines or less. This seemed crazy to me, but the authors proceed to defend their position quite ably. I then tried their advice on my current project, and lo and behold my code got cleaner, more logical, easier to extend, and easier to maintain.
I had similar reactions to other guidelines, like limiting code complexity within a code unit to 4 branch points and limiting function parameters to 4. I also had similar positive experiences from implementing them.
Other chapters are less revolutionary but still worth rigorous application: avoid copy-and-paste (instead genericize the code you're copying so that it applies to both use cases), write automated tests, and loosely couple components. You may have read of these things before, but the explanation and defense helps to settle them into the reader's mind and encourage him or her to practice them consistently.
Displaying 1 - 22 of 22 reviews