To document or not to document? An exploratory study on developers’ motivation to document code

caise_2015Last week at Stockholm, Sweden, at the Conference on Advanced Information Systems Engineering (CAISE’15), my colleague Yulia Shmerlin presented our paper at the Workshop on Cognitive Aspects of Information Systems Engineering (COGNISE). This is joint work with Prof. Irit Hadar and Prof. Doron Kliger from the University of Haifa, and is a sequel to our previous paper on Documentation Debt that was published last year.

Title: To document or not to document? An exploratory study on developers’ motivation to document code

Abstract: Technical debt represents the situation in a project where developers accept compromises in one dimension of a system in order to meet urgent demands in other dimensions. These compromises incur a “debt”, on which “interest” has to be paid to maintain the long-term health of the project. One of the elements of technical debt is documentation debt due to under-documentation of the evolving system. In this exploratory study, our goal is to examine the different aspects of developers’ motivation to document code. Specifically, we aim to identify the motivating and hindering aspects of documentation as perceived by the developers. The motivating aspects of code documenting we find include improving code comprehensibility, order, and quality. The hindering aspects include developers’ perception of documenting as a tedious, difficult, and time consuming task that interrupts the coding process. These findings may serve as a basis for developing guidelines toward improving documentation practices and encouraging developers to document their code thus reducing documentation debt.

You can freely download the paper.

Below are the slides of our presentation at the workshop:

Please share your comments below.

Posted in Psychology of Programming, Research, Technical Debt | Tagged , , | Leave a comment

The SOLID Principles Illustrated by Design Patterns

The Clean Code Alliance in Israel organized a special event about the SOLID Principles of Object-Oriented Design. I was glad to be invited to give a talk about “The SOLID Principles Illustrated by Design Patterns”. My friend Eyal Golan also gave a very nice talk about the Single Responsibility Principle.

Title: The SOLID Principles Illustrated by Design Patterns

Abstract: The goal of the SOLID design principles is to improve the Separation of Concerns, through weaker Coupling and stronger Cohesion. The main consequence should be software systems that are easier to maintain and to extend. However the definition of the SOLID principles is quite abstract, and some developers find it difficult to apply them in practice. In my talk I will show how well-known Design Patterns illustrate the application of the SOLID principles, and also show examples of how to follow these principles to Refactor and improve existing designs.

Bio:  Hayim Makabee was born in Rio de Janeiro. He immigrated to Israel in 1992 and completed his M.Sc. studies on Computer Sciences at the Technion. Since then he worked for several hi-tech companies, including also some start-ups. Currently he is a Predictive Analytics Expert at Pontis. He is also a co-founder of the International Association of Software Architects (IASA) in Israel. Hayim is the author of a book about Object-Oriented Programming and has published papers in the fields of Software Engineering, Distributed Systems and Genetic Algorithms.

These are the original slides of Hayim’s presentation:

Here is the video of the talk (in Hebrew):

I would like to thank Boris Modylevsky and Itzik Saban for the organization of this event.

Feel free to share your comments below. Thanks!

Posted in OOD, Design Patterns, Software Architecture | Tagged , , | 5 Comments

Rotem Hermon on Change Driven Design

At the last meeting of the TLV Software Architecture Meetup, Rotem Hermon, VP Architecture at Gigya, gave a very interesting talk about “Change Driven Design”.

Title: Coding Changes

Abstract: Every developer knows that the only constant thing is change, and every developer has the scars to prove it. When we come to designing and writing software, we should make handling change one of our main concerns. We all pretty much do it, even if we don’t usually call it that. In this talk we’ll discuss the four principles of Change Driven Design. We’ll also explore some software architecture methodologies that position handling change as a core concept and design principle.

Change Driven Design

In particular I like very much Rotem’s definition of the four principles of Change Driven Design:

  1. Areas of change should be contained.
  2. Things that are more likely to change should be easier to change.
  3. Things that are less likely to change should not depend on things that are likely to change.
  4. Change should entail extending the system rather than refactoring.

I believe my proposal of Adaptable Design Up Front (ADUF) is a good example of the application of these principles to high-level design.

These are the original slides of Rotem’s presentation:

Here is the video of the talk (in Hebrew):

Please share your comments below.

Posted in Adaptable Design, Software Architecture, Software Evolution | Tagged , , | 3 Comments

Do SOLID design principles make code slow?

SOLIDThis week one of the readers of my blog asked me this question:
“Do SOLID design principles make code slow?”

I think this is a very interesting question, which I have already encountered several times during my 20 years as a professional software developer.

This question became even more common with the popularization of Agile methods, that in general focus on simplicity following principles such as KISS and YAGNI. While I agree that we should try to keep things simple, I think that over-simplification is extremely dangerous.

The SOLID principles of object-oriented design are:
Single Responsibility principle
Open/Closed principle
Liskov Substitution principle
Interface Segregation principle
Dependency Inversion principle

The goal of these design principles is to improve the Separation of Concerns, through weaker Coupling and stronger Cohesion. The main consequence should be software systems that are easier to maintain and to extend. Thus the application of these principles may be seen as an investment in the quality of the software design that has future benefits for the system’s evolution.

However, some potentially undesirable consequences are:
– The proliferation of relatively small concrete classes.
– The proliferation of abstract classes and interfaces.
– A high number of levels of indirection.
– Too many abstraction layers.
– Increase in the depth of the inheritance tree.
Yo-yo problem.

Thus the indiscriminate application of SOLID principles may in practice increase too much the complexity of software systems, with negative consequences for maintainability and extensibility. This is the reason we need experienced software developers in a team, who have the wisdom to foresee the consequences of their design decisions.

Back to the original question: “Do the SOLID principles make code slow?” As we have seen, this is one possibility, because of the potential increase in the levels of indirection and in the number of abstraction layers. In other words, we may be forced to make more method calls and aggregate the data we need from several small objects.

My advice is to choose a design that is clean, focusing on the separation of concerns, but still as simple as possible. If there are performance concerns, this should be measured using runtime tools such as a profiler. Only if a clear bottleneck is detected should the initial design be modified to make the code faster. In any case, the definition of “slow” and “fast” depends on specific system requirements.

To end with a quote by Donald Knuth: “Programmers waste enormous amounts of time thinking about, or worrying about, the speed of non-critical parts of their programs, and these attempts at efficiency actually have a strong negative impact when debugging and maintenance are considered. We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil. Yet we should not pass up our opportunities in that critical 3%.”

Do you agree? Please share your experience in the comments below.

Posted in Agile, Design Patterns, OOD, Programming, Software Architecture | Tagged , , , , | 10 Comments

Finding your purpose in life

How to find your purpose in life? The Venn diagram below has appeared several times on the social networks I use. In my opinion it is very interesting and makes me think, so I would like to share it with you and make some personal comments.


You Love It vs. You Are Great At It

Probably there are many things that we love but that we are not great at. But the opposite is not true: I don’t believe we may be great at something we don’t love. I think that nothing is more effective than enthusiasm. Thus in the Venn diagram above, all the things we are great at should fall in the intersection with the things we love. I talk more about that in my post about the 10,000 hours rule.

You Are Great At It vs. You Are Paid For It

On the short term we may be paid to do something even if we are not great at it. But on the long term we will only be able to hold a good job if we are great at it. So on the long term there is always an intersection between being great at and being paid for something. Moreover, being great at something is not simply a status we reach and then enjoy. Being really great requires continuous improvement.

You Are Paid For It vs. The World Needs It

I believe that if we are being paid for something it is because the world needs it. Thus all the things we are being paid for fall in the intersection with the things the world needs. Of course there are lots of people working as volunteers on things that the worlds needs. But I also believe that if there is something that the world needs, there will always be someone willing to pay for it.


  1. All the things we are great at fall in the intersection with the things we love.
  2. All the things we are paid for fall in the intersection with the things we are great at.
  3. All the things we are paid for fall in the intersection with the things the world needs.

Thus to find your purpose in life, you just need to find something you love and that the world needs, and then make sure you are great at it. That simple. :)

Posted in Efficacy | Tagged | 1 Comment

IASA IL Workshop: Philippe Kruchten on Managing Technical Debt

pkruchtenThe first activity of IASA Israel in the year of 2015 was a full-day workshop by Prof. Philippe Kruchten on “Managing Technical Debt”. The workshop was highly interactive with many questions from the audience. Prof. Kruchten covered the subject of Technical Debt with depth and details, bringing many relevant references and concrete examples from the industry. By the end of the day, the workshop participants, including me, had a much better understanding of the causes and consequences of Technical Debt, as well as some tools and techniques to manage it.

Title: Managing Technical Debt


Technical debt is a metaphor to explain a common phenomenon in software development projects: A design or construction approach that’s expedient in the short term but that creates a technical context in which the same work will cost more to do later than it would cost to do now (including increased cost over time).

While the metaphor has gain a lot of success, lately, it is still a rather vague or mysterious concept in many organizations, who are struggling to detect, measure assess, and remedy their technical debt. In this workshop we’ll explore the various facets of technical debt, discover how to characterize it, measure it where possible, and develop strategies for prevention and for remediation.

Presenter Bio

Philippe Kruchten is professor of software engineering at the University of British Columbia in Vancouver, where he retired in 2004 after 30+ years in industry, primarily with Alcatel and Rational Software (now IBM). He developed a software architecture method in the early 1990s, and led the development of the Rational Unified Process from 1996 to 2003. Over the last few years he has led a research effort to better characterize technical debt, in particular intentional, strategic technical debt, at the architectural level. He has organized a series of research workshops on technical debt in Pittsburgh (2010), Honolulu (2012), Zürich (2012) San Francisco (2013), and Victoria (2014), and he has written several papers on the topic, notably with his colleagues at the Software Engineering Institute. He is the co-founder and past chair of Agile Vancouver.


You can download the slides of a previous presentation.


Technical Debt is a metaphor introduced by Ward Cunningham in 1992 to help us think about a problem that is crippling many software endeavours. In his metaphor, doing things the “quick and dirty” way sets us up with a technical debt, which is similar to a financial debt. Like a financial debt, the technical debt incurs interest payments, which come in the form of the extra effort that we have to dedicate in future development because of this quick and dirty design choice. We can choose to continue paying the interest, or we can pay down the principal by refactoring the quick and dirty design into the better design. Although it costs to pay down the principal, we gain by reduced interest payments in the future.

The metaphor saw little use for many years, but suddenly around 2000 and curiously in parallel with the advent of agile methods (though this may be just coincidental), it met quite some success, especially in the blogosphere and in many software gurus’ sermons. And the phrase started to be used to label all kinds of software ills. Since 2010 it became the subject of more scrutiny and researchers have attempted to better understand the concept, define it, measure it, assess its impact, and propose tools and methods to manage it.

A more recent definition of technical debt which seems to aptly convey the current consensus is given by Steve McConnell: “A design or construction approach that’s expedient in the short term but that creates a technical context in which the same work will cost more to do later than it would cost to do now (including increased cost over time).”

While the phrase ‘technical debt’ is used a lot now in industry, is it really a useful concept, that can lead to improvements, or at least a better understanding, of the way we develop software? It is probably a useful rhetorical concept, as pointed out by many to start a dialogue between business people and technical people about schedule pressure, architecture, poor internal quality, release planning. But it is hard to go beyond the rhetoric and get to the point where it leads to actionable, objective, concrete facts, data, techniques or even tools.

One of the issues is that the metaphor has been applied loosely to a vast range of issues or concept, and that the metaphor, like any good metaphor, has its limits and we should understand what these limits are: technical debt in software development is not literally a financial debt, like a mortgage. “…there is a plethora of attention-grabbing pronouncements in cyberspace that have not been evaluated before they were published, often reflecting the authors’ guesses and experience on the subject of Technical Debt.”

This being said, the metaphor proved to be useful, and large organizations have explicitly introduced it in some form of another in their software development process, as a something to identify, value, and take into consideration while planning iterations and releases; one such example is Cisco in Ireland.

This workshop was organized in cooperation with ILTAM. Please share your comments below.

Posted in IASA Israel, Software Architecture, Technical Debt | Tagged , , | 1 Comment

Helping new immigrants to find a job in Israel

gvahimThis month I had the pleasure to give a talk to a group of young new immigrants. Immigration to Israel is called Aliyah, and the new immigrants are called Olim. I am a volunteer at the Gvahim organization which has the goal of helping new Olim. In particular, Gvahim helps highly-qualified young people with academic background and relevant professional experience. One of the main challenges for these new immigrants is to find an appropriate job in Israel, because most of them have only basic Hebrew skills.

The participants in my talk were mostly from the IT and software development field. I tried to give them some concrete and practical advice on how to find a good job in Israel. I also discussed some possible approaches to making connections in the Israeli software industry. Finally, I emphasized the importance of having realistic expectations. You may see the slides of my presentation below.

If you are a young professional considering Aliyah, you should contact Gvahim. Please feel free to leave your comments below.

Posted in Israel | Tagged | Leave a comment