Software Architecture tips II - Illuminate don't detail

Illuminate don't detail

Another common problem is that of "wallpaper" diagrams, a kind of "one diagram to rule them all approach". This leads to one diagram which is normally static, that shows all the components in the system and attempts to show multiple axis of interest (protocols, deployment, technology).

It's wallpaper as people then proceed to stick it on a wall and refer to it in all conversations - the issue being that no one apart from the author knows what it means (and sometime even they don't), its notation is secret, and its not normally kept up-to-date.

But prehaps the worst sin is that the diagram is just too complex! it is better to have a few simple diagrams that show a system from different views (static, dynamic, deployment) and a few key scenarios (startup, failure, major business cases etc) - so each diagram should illuminate a design approach and decisions taken, rather than trying to get all the detail on one page.

Another advantage of the "illuminate don't detail" approach is that it leaves space for other decisions to be made later, as trying to detail everything at the start leads to design decisions being made that are not based on delivering a user story, but on the need to nail down everything.

Software Architecture tips I - Dynamic rather than static

Dynamic rather than static

One of the common problems in software development is that people tend to draw static diagrams, these are good for the person that drew them but often hard to understand out of context. So for example people tend to draw class diagrams (http://www.agilemodeling.com/artifacts/classDiagram.htm) but not activity diagrams (http://www.agilemodeling.com/artifacts/activityDiagram.htm). You may want to try drawing an activity diagram of one of your existing systems, to get into the mindset of thinking about systems over time.
 
Time or sequence based diagrams allow people to see more clearly which parts of a system work together to deliver a user story or scenario. Even a class or object diagram which only show the entities involved in a story fails to deliver the visceral understanding that activity or sequence diagrams give.
 
(I'm organising some architecture training at work, and I needed to give a few tips to get people thinking.)

Development's Naive Cynicism

Development is the process of creating a new product or release. In any development team or group there is a generally an accepted "right way" to develop a product (especially in the pathological team of one). However what I've observed in practice is that individuals in the team rarely follow the "right way” and bizarrely act (or report) as if the team is – I’m naming this behaviour as “Development's Naive Cynicism” (DNC)

Being cynical about the "right way"
We are cynical as we know what the "right way" is, but chose not to follow it. "Our process says do X and Y, but no-one does that!" is a common line. I'm not suggesting what the right way is or that there is only one "right way". The definition of "right way" changes dependent on approach (agile, lean and waterfall etc), constraints (time, money and skills etc) and suitability (complexity, duration and urgency etc) etc. Also two teams can have very different views of what the "right way" is, however within a team an agreement of "right way" is possible and desirable.

Being naive
We are naive as know that everyone is cynically not following the "right way", but chose to behave as though we do not know this. This becomes extreme in the case of a team of one, where we default to a sub-optimal approach as the "right way" is too much effort. Given that the definition of "right way" is under our own control (as we define it) this behaviour is bizarre - we chose not to redefine the "right way" (as we secretly know it IS the right way), but instead betray ourselves.

Why does Development's Naive Cynicism exist?
Let us recap: Development's Naive Cynicism = we know the right way, we don’t follow it, but pretend we are following it. What would cause us to exhibit this behaviour?

• Incorrect definition: the "right way" is not the right way, at some level we don't really believe in our definition of "right way". But do we ever make the effort to fix/redefine it?
• Self analysis: introspection is hard, and generalising our behaviour difficult. But why spend so much time learning if we don't seek to improve our core (kernel process) competence.
• Time: I've got a product/release to ship, get out of the way! But surely (and don't call me Shirley) we know that we would be faster, quicker and lighter etc if we did it the “right way”.
• Laziness: it's too much effort, no one else is doing either! Not really going to be a professional with this line of thinking

I think one of the main reason that DNC continues is the effort/reward perception, and durability of desire - only a slow steady improvement in process seems to work (big bang changes fail), which yields slow rewards, factored in the difficulty in persisting with continuous improvement makes it a difficult for an individual let alone a collective to eradicate it. A secondary issue is complexity, as technology progresses it tends to create complexity, however there is not a matching effort put in to change processes to cope with this - so overtime all processes become unfit for purpose.

That leaves us with two choices:

• Stop DNC: either by living up to the promises made by our "right way", or redefine our "right way" to reflect what we actually do
• Continue with DNC: maybe it does not exists, maybe it’s not that important or maybe it’s too painful to face into?

Requirements: Non-directive interviews

Reading the Economist's article "The avatar will see you now" I came across:

"Meanwhile, a real person alongside the participant will answer any questions and, after the virtual visit is over, Dr Conboy-Hill will carry out “non-directive” interviews, a technique used by the police to encourage witnesses to choose what they want to talk about and to maximise recall"

What interested me was the snippet about "non-directive" interviews - it sounded like a technique that might be worthwhile for requirements gathering - I subsequently found "ACTIVE LISTENING IN THE NONDIRECTIVE INTERVIEW" which I think there are a few tricks worth picking up - especially rephrasing and the "brake shoes"...

of course I'm a sucker for any document that uses the word "interlocutor" ;-)

Pentasolve: a problem solving approach.

I'm adopting a new technique today, Pentasolve: a problem solving approach.

Principally this means when faced with a [technical] questions I will attempt to generate five candidate answers.

I will then select the best answer. I'm doing this for a number of reasons:

• Creativity: It will force me to consider more left-field solutions.
• Peer pressure: It will allow any "obvious" solutions to have peers that it can be evaluated against.
• Maturation: This process will give ideas more time to evolve before I fix on one.

Why five? no scientific answer to this - three seems too small (I can always think of three, five forces me to think). More than five seems to be overkill.

I'm about to attempt a relatively complex product development, so I will see if this technique helps or not.

Pentasolve^TM - solving your problems 5 steps at a time ;-)

Sit back, relax and program

Whilst at university *cough* poly-university I spent a lot of time writing code. My landlord was also studying at the time (Maths and Operational Research) and he was writing a lot of code as well.

Now I can't remember who coined the phrase, but one of came up with a term to sum up the feeling you get when writing code - or more importantly the feeling you need to have before your start:

Sit back, relax, and program

The feeling you have when you are writing good code is captured in this phrase, and the wierd thing is that if you seek this feeling when programming you write better code. A kind of Zen and the art of programming*

*I'm guessing someone copyrighted this phrase as some point... ;-)

Big-oh no notation

Whilst doing some revision for an exam I had to refresh myself on Big-Oh notation which showed me how much is taken for granted by documentation writers.

I refer of course to MSDN, which there appears to be little reference to this notation - the notable exception being "An Extensive Examination of Data Structures". Why does this matter? well if you are trying to work out what the order of magnitude of your code is then you need to know what the underlying framework is doing.

IMHO the collections classes and other such constructs should have their Big-Oh documented against them in the class library.