Coherent, in principle

April 3 2012

intrigued by a recent thread on the Italian Extreme-Programming mailing list (sorry, registered members only), I just remembered I collected thoughts about design principles, that I didn’t shared yet.

basically, I tried to map the “overlapping” between the 5 SOLID principles and the 5 GRASP “primary” principles. in my view, they address four basic topics:

  • flexibility (aka software evolution)
  • encapsulation
  • coupling
  • cohesion

sure, that’s nothing new, and they are all related each other. it’s just a quick reminder: “what’s DIP all about? coupling”, “what about Creator? encapsulation!”.

regarding (functional) cohesion, Larman’s book provides a broader context for “measuring” how much an object is cohesive: number of functional areas, number of responsibilities.

sure, this could sound too “academic”. and in fact I can’t keep from smiling and thinking about Dead Poets Society, quoting the “PIG” graph:

“If the poem’s score for perfection is plotted along the horizontal of a graph, and its importance is plotted on the vertical, then calculating the total area of the poem yields the measure of its greatness.”

anyway, High Cohesion principle suggests designing objects with “few responsibilities, in one single functional area”. SRP goes further, saying an object should have a single responsibility. but this doesn’t mean having “one-(public)-method” objects: High Cohesion clearly doesn’t mandate this, nor SRP.

object services (aka published interface) should be narrowed around its single responsibility. Bob Martin says objects with “one reason to change”. so, having only one public method is an option, but not a requirement, as long as published interface consists of few methods, all belonging to the same functional area, all evolving together.

yep, this is hard to achieve. while “few methods” and “one functional area” are easier metrics, something you could understand looking at the code at any given moment, “evolving together” implies monitoring the future, tracking code changes, like commits in a revision control system. given a class, had all its changes a common reason?

I think I’m watching the Dead Poets Society movie again, tonight!


One step up

February 7 2012

it’s going to take so much longer than I expected for me to achieve a good enough writing about this topic, so I decided to start small, share a few initial thoughts, and collect feedback. abstract: what about design concepts and principles when applied at the system level? I mean, do they still stand? is there anything I can learn from the object level?

I’m playing with architecture these days. yes, playing is the right word. I’m almost in a brain-storming phase, reading books and articles, writing mind maps, and collecting data from current and past projects I’ve been involved with. but the analogy soon came clear: what about good design principles, evaluated as architecture principles?

so, here they come just rough bullet points.

information hiding. don’t let implementation details of a given component pollute the system. should client code be aware of persistence mechanics or sorting algorithms? no, it shouldn’t. this information should be hidden inside the component providing those services. so, at the system level, why do we consider integration databases an option? why don’t we hide implementation details such as relational database systems (DMBS) and query language (SQL dialect)? wouldn’t be better to stick on a shared data format, such as JSON, XML or CSV files?

encapsulation. support cohesion and keep related logic together, near data logic works on. don’t ask for values, but tell behavior to be executed. sure, this is strongly related to information hiding. but, what about system design? what about telling a system to perform a given task, instead of asking for data? public APIs and application databases are recipes you can select from your architecture cookbook.

ports and adapters. achieve an isolation level from external dependencies in application code: publish a clear service interface (port, facade) in the application, and provide an implementation (adapter) to a specific external service or toolkit. this is also known as hexagonal architecture. well, when it’s time to design system dependencies, what about putting an extra layer of abstraction, protecting your system from external systems implementation details? this idea is what Pryce and Freeman call simplicators. this video by Pryce explains the idea further, presenting a system where all external systems are accessed through an intermediate HTTP facade, which completely hides those protocols details and pitfalls.

to recap:

  • share database among multiple applications: don’t! consider databases as object internal state, which you’d probably not expose publicly. would you?
  • export data from application databases for reporting, calculations, and so on: don’t! consider those exported data as object getters, which you’d probably not publish as part of object interface. would you?
  • provide connectors to external systems and toolkits in application: to be fair, not so bad. but consider encapsulating them in one intermediate system

does it sound good to you?
to be continued..

Video from IAD 2010

December 9 2010

just updated personal page adding links to both slides and video for the presentation I had at the last Italian Agile Day 2010. enjoy!


November 6 2009

i’m back.

for the last two weeks, i’ve been staying in the lovely city of Amsterdam, working for a customer of my dutch colleagues. challenging, amusing, funny and resource-consuming, here’s a brief recap of my last 15 days.

first of all, thanks from the deep of my heart to Maurizio “daje forte” Mao Pillitu, for hosting me in his nice and comfortable home, just outside the city town. he’s been very kind and friendly, i hope i had in some way paid back with my italian-style cousine.

so, i’ve been working for Hippo, a young and energetic open-source company born around their CMS product: it’s a nice building down-town, just 15 walking minutes far from Dam square (yep, i loved walking through the city lanes after a full day of working). guys at Hippo are friendly and passionate, devoted to open-source; they also organize forge-fridays, sort of coding dojos with the focus on releasing working plugins (for Hippo CMS, of course) at the end of the afternoon.

Hippo CMS is having a lot of popularity among public institutions in the Netherlands, something my dutch colleagues have been working on hard also. but even if Hippo 7 is getting popular, there are still a lot of projects done with the older product version, Hippo 6. And that’s were my story begins.

i’ve been working for the municipality of Schijndel, a little dutch town, helping its IT management improve and automate meeting’s agenda and reports publishing. yeah, you heard it right: they record and publish (with a little delay, of course) audio and text content for every council’s meeting. being an italian citizen, all that transparency and devotion sounds strange, but is really laudable.

the first challenge i faced was, of course, translating all documentations from dutch to english, from analysis PDF to past emails with customer. i didn’t had everything clear at first, but thanks to double-checking with dutch colleagues i finally got it. (anyway, it’s funny almost every translation from dutch gets verb in the very last part of sentences. it really reminded my latin classes, while at college).

then i finally entered the dark tunnel: technology viscosity and indecent web of dependencies, also known as Maven 1. gosh, i really had to work hard to have a successful build on top of Java 1.4, Axis2 and Cocoon 2.1, which turned out to be classpath monkey-patching, using ant tasks, jelly scripts and maven postGoals. damn!

add lack of support from webservice’s developers and consultants, and the soup is ready to be served! in fact, i just had a working test environment (i mean, representative of customer’s one, with valid data) almost 3 days before the project scheduled end. that’s awesome, isn’t it? how did the hell i managed to get the work done?

applying what i later called the “abstract and adapt” strategy: understand the domain, abstract from implementation details, then adapt code when things get clearer. well, that’s the hexagonal architecture (but, you know, we like coining sexy names). so, i spent the whole first week coding the application logic decoupled from real system behaviour, which in fact was unknown. Agenda and its Repository, Content and Storage, Indexer and Importer, these are all roles i’ve been writing, test-driven, from day one. that’s not easy, and of course it’s risky; but it was the best i could do.

reading webservice specifications and WSDL, i could also guess how that slimmy layer should behave, but i really got it wrong at first! then, i had an ah-ah moment during the first weekend, and changed the webservice adapter in order reflect my new thoughts, without the need to modify domain logic so much (in fact, i also improved my domain knowledge). i changed unit tests, and added sort of spikes: tests with no assertions, just logging actual parsed responses, so that i could “see” with my eyes current webservice behaviour, at each test run.

and i was right! i clearly remember how shocking was reading in the console log some parsed data, when they finally were set up on test environment! you know, i was going for lunch, i ran all tests one more time, before locking down workstation, and i saw that: “parsed 6 agenda”, following by a so-nice full toString(). that was awesome, really: my tests told me setup was done before receiving a confirmation email by consultants, 30 minutes later!

than, i had my journey to Schijndel, to discuss deployment and testing on customer’s network. trip took 2 hours, i also had a 30 minutes stop in ‘s-Hertogenbosch which i spent walking down-town, among nice gothic buildings and golden dragons.

it’s shocking how efficient dutch national transports website is, with its door-to-door journey planner, really. well, it’s a shame it’s not updated with temporarily moved bus stops, which could have saved me one hour in the late evening!

anyway, that’s it, a recap of techy stuff mixed with journey reports. thanks to the whole dutch office for the opportunity and drinks, looking forward to next works together!

as usual, switching to a new project, i like to perform a code review on my own or while pairing, looking for un-emerged design or simply for duplications; that’s really the funniest thing for a design-maniac like me. sometime nice hints do come, sometimes don’t (probably because the design is good enough given actual goals).

so, last week i’ve moved to an existing codebase, and while pairing i noted down on paper some complexities i found on code; later, with all green bars, we tried to simplify a bit. what mainly come out was a revisited model-view-controller triad for a reporting system.

my preferite part was the formatting stuff: some nested complex loops became a composition of Formatters, each taking care of a small amount of rows (details, total) or columns (descriptions, calculations, and the like).

as we started a new story, i paid attention to how much code was reused: not as much as i supposed, and that was really a shame, even if code was clearer. today was our payoff.

we found a bug on a report. given a collection of aggregates, we expected to see details for first aggregate, then a summary for its total, followed by details for second aggregate, then second summary, and so on. instead, result was all details followed by all summaries. there was something wrong with how Formatters where composed. fortunately, that wiring was in one single point.

so, it turned out that it was just a matter of composing Formatters in a different way. from today journal:

we fixed a bug on rows order moving from a composite with two section formatters (details, summary) to a section formatter with a composite (details, summary). flexibility powered by OO.

day by day, i’m learning the difference between flexibility and generality (as Wake’s Refactoring Book helped me understand).

moreover, it now seems it’s also easier for us to estimate tasks, having clearer boundaries and reusing code. and, off course, knowing more about domain logic.

being honest, there’s a lot of noise due to Java generics! if only we could use .NET implementation..

iterative and incremental development means delivering functionalities one at a time driven by some priority critera (e.g. business value). similar functionalities happen to be developed not all at the same time. so, design focus on supporting all the functionalities planned for a given iteration, and nothing more. key to succeed are simplicity, flexibility and a wide automatic test suite.

imagine a financial project where customer needs to process via nightly batch all monetary transactions received daily. he ask for supporting critical calculations first, and set at lower priority to automatic double check (it can be done manually in the meantime). in a plan of a few months, 3 or 4 different calculations are going to be developed.

but we start from the first one, and let the code (aka design) support the others later.

just after the first user story get signed, design consists of three main roles:

  • a BatchCommand that collects items and process calculations, and then updates state on items (e.g. date processed)
  • a Gateway to the database that knows criteria to filter items and knows how to select and save items from/to the database
  • a Connector in charge of handling connection to the database

here’s a brief recap using CRC cards:


next iteration starts, and customer select another calculation to be developed, which just differs in selection criteria. then, the team has to find out the simplest way to support this scenario. well, a few exists, of course. in this post, i’m focusing on some design strategy we can use, comparing them.

we need to change Gateway selection criteria. someone says go for inheritance, and override criteria in a subclass. someone else says use composition, and move responsibility to change into another object. you choose, me too: composition!

so, we change Gateway to delegate a collaborator to gather selection criteria: let’s say, a CriteriaBuilder, even better as an interface. with our favourite IDE we perform an “extract method” refactoring followed by “move method”, moving selection criteria to a criteria builder. then, we add another builder for current user story. finally, it’s just a matter of wiring two Gateways with two CriteriaBuilders. design ends up being like this:


what’s wrong with this? well, nothing i would say, dependencies are well handled: low-level details (Gateway) depend on abstraction (CriteriaBuilder interface) and high-level policies (concrete CriteriaBuilders) don’t depend on anything, they provide that abstraction. in other words, we succesfully applied Dependency-Inversion Principle. so, again, what’s wrong?

we created two different gateways, that’s the matter, in my view. we stated Gateway is an infrastructure detail, it “knows how to select and save items from/to the database”. so, why do we need two different ones? has infrastructure changed? not at all.

in OO an object has an “outside” and an “inside”. GoF, in the Decorator pattern, to explain this simple rule used the metaphor of an object skin and guts:

“Changing the skin of an object versus changing its guts. We can think of a decorator as a skin over an object that changes its behavior. An alternative is to change the object’s guts. The Strategy pattern is a good example of a pattern for changing the guts.”

now, imagine we move selection criteria “outside” from Gateway, into another object which collaborates with the Gateway, but doesn’t hold a reference to it: it wll be sent as a parameter of the message “please, apply selection criteria on this gateway”. let’s say we name this new role a Selector. we end up having one Gateway and two Selectors, this way:


that’s it.

to recap, my suggestion to you while doing design: whenever you find an opportunity to simplify object responsibilities, moving some of them away, ask yourself “is this a domain or an infrastructure issue?”. if possible, avoid mixing the two: leave objects cohesive, and apply DIP. then, all other things being equal, avoid having more instances of a given infrastructue class, unless you really need to set different infrastructures (in this example, a gateway to filesystem or an in-memory one).

as Beck says, “Design is beneficially relating elements”.

It seams open

May 4 2009

i can clearly remember when i first discussed DIP and OCP with others: it was two years ago, during my apprenticeship as an XPer. to me, it was nothing new, i already had studied all the principles that now come under the SOLID ancronym. but, probably, i hadn’t digested them enough: something that just came later with experience.

Dependency Inversion was for sure my favourite since then, for its multiple implications depending on what “high level” and “low level” mean; in my view, there are at least two meanings: abstraction (high level policies vs. low level details) and layering (close-to-user layer such as GUI vs. infrastructure layer). much more, i loved its love-hate with Dependency Injection (maybe more on this in a separate post).

Open-Closed is harder to understand, at first. how could you “change without modifying”? abstraction is the key! let modules depend on abstraction, then provide new implementations when behaviour has to change, without the need to modify existing code. in other words, always depend on abstraction: which, in the end, is DIP itself. OCP and DIP are such “yin and yang” in software design: they help achieve each other.

then, when i first discussed OCP with team-mates, i pushed for an analogy with Feather’s Seam Model. it’s discussed in “Working Effectively with Legacy Code” book: use seams to let legacy (which means untested) code be tested. to be fair, my analogy was not welcomed too much! i had to force my thesis a bit, and in the end not everybody was convinced.

two years later, it happened again! indeed, a few months ago we had a study group on OCP. i was in charge of preparing material to study on, and i chose a few corollary articles: first chapter from GoF Design Patterns book, which focuses on “design targeting interfaces”, and WELC chapter 4 “the Seam Model”. this time i was more convincing, and the analogy between OCP and the Seam Model became clear during our study session! and now, i want to tell you too.

after reading the bunch of articles i prepared, i asked a colleague to state in a few words what OCP was about. he said “change behaviour without modifying code”. great! then, i asked him again to state what the Seam Model was about, and he said “let code behave in a different way without modifying it”. well.. nothing left to say!

abstraction is the key, that’s true. but what about code which doesn’t follow OCP/DIP? it doesn’t depend on abstraction. we can modify it, refactoring, but we need an automatic test suite, in order to guarantee no behavioural change. and that’s exactly what Feather’s model is about: change code a little bit putting seams, to test it in isolation.

on the other side: what seams can you use to test OCP-compliant code? of course, already existing abstractions: you just have to change enabling points (in a test, usually in fixture setup).

in the report for our study session, on our internal wiki, we wrote:

We then discussed what OCP and Feather’s Seam Model have in common:

  • they seem the same idea, applied to reach different goals
    • OCP: put abstractions to isolate from future source code changes
    • Seam: put abstractions to test applications without changing its source code
  • to recap
    • closure/abstraction = seam
    • “main() routine”/factories = enabling point

to be precise, Feather’s model is about three different techniques, useful for testing legacy code written in any language, not just object-oriented ones. he talks about preprocessing seam, linking seam and object seam. so, the analogy with OCP is just between abstractions and object seams, even if sometime linking techniques are also used to achieve abstraction (such as reflection or some configuration-based IoC tool).

so, when i watched Misko‘s clean-code-talks videos, i was surprised to hear him use the term “seam” while talking about DI and SOLID principles: he confirmed my analogy have sense!