Balsamiq Mockups

This is an excellent wire frame tool: http://balsamiq.com/products/mockups

OOA/D with UML and OO Patterns – Conceptual Domain Model

This post is based on the 2nd Ed. of Craig Larman’s most excellent “Applying UML and Patterns”.

Welcome back for yet another adventure into the bright and colourful world of Craig Larman (CL) and UML. I got a slightly tricky domain that I have done some Use Cases for, and now I want to single out one of the high risk areas and start an iteration focused on this – and to gain a good OO basis to start from, I’ll be doing a conceptual Domain Model using UML – and in particular the community edition of Visual Paradigm for UML 7.0. Nice free tool to get you started with UML.

Can you think of anything better to do with an afternoon? Me neither.

So how did we get into this mess in the first place? Well, we decided we wanted to do OO analysis, and Domain Models is one of the core building blocks in Larman’s approach to this. And we like and trust Larman. The essence of OO analysis is division by conceptual classes (not functionality) and the subsequent allocation of responsibilities to these.

So, what is a Domain Model (DM)? Well, it’s a conceptual visualisation of the objects within (a part of) our business domain. So this is still nothing to do with actual Java or C# classes, we are thinking in terms of real world or virtual world actors here. Note that UML does not actually supply a specific syntax for this, so what you do is simply use Class Diagrams, but leave out any code specific details.

ScreenShot016Also, note that we are still in a agile and iterative process (Unified Process) – so don’t try to create a DM that covers every single possible object, association and attribute of your domain. In stead, focus on a high risk area, and within that in your DM only focus on details that are of interest for your current iteration and focus.
If you leave something out, you can revisit this and refine your DM in later iterations. Be cool! Cool as a cucumber. However, don’t try to over-simplify the area you are focusing on. As a general rule more conceptual classes are better than few. Don’t be a pansy. Also note that some objects might only have a behavioural role, which is fine.

So how do we find these blessed conceptual objects?

Well CL recommends using a) a Conceptual Class Category list and b) Identifying Noun Phrases.

I will skip over the first one a bit lightly as I find it a bit rigid and unintuitive – basically it’s a load of categories that you can use as triggers for your poor brain. I found the list online in a word document here if you’re interested:  https://cs.senecac.on.ca/~mary-margaret.walton/conceptualclasscategorylist.doc
Our thanks to Mary Margaret.

Much more fun is going through your Use Cases looking for Noun Phrases!
Now, of couse this is just natural written language with all it’s nuances and ambiguities so you cannot just do a one-to-one mapping, but you’ll work it out.

Either way – all you do now is plunk these into a Class Diagram – and then we’re onto Attributes and Associations. Happy days!

But no! Hang on a mo – first we must head a few words of caution from our wise friend CL:

  • If something is of a simple datatype (string, number) it’s most likely an Attribute.
  • Beware that you will quite often find a need for Definition object and an Instance object. See below here:
    ScreenShot017So the key here is Normalization really – we do not want to duplicate the description and price for every item, and also we need to retain these even if there is currently zero items in the system. (Larman cooks up this elaborate example about flights and some airline disaster where all flights are cancelled, but we have to retain the flight information. Think he might be suffering from post 9/11 trauma).
  • Finally CL recommends “lowering the representational gap” by choosing real world names. I don’t know what else you would do really, but nonetheless it makes sense.
  • Finally, finally – don’t spend days on this, CL says that with some experience you should be able to do a DM from some good Use Cases in a few hours. It’s important, but it’s not rocket science – so don’t worry if you finish it quickly. That’s ok, have a Doughnut.

Adding Associations

Right, probably main sticking point here will be the UML syntax, so let’s cover that. From CL’s book:

ScreenShot018

Note that the direction arrow is just an aid to the text.

Big question is of course, how do we identify the correct associations? Well, two ways: 1) Consider relationships where knowledge of the association need to be recorded or preserved for some duration, and 2) use the Common Associations List below to check through the conceptual objects you have identified.

Category Examples
A is a transaction related to another transaction B CashPayment—SaleCancellation—Reservation
A is a line item of a transaction B SalesLineItem—Sale
A is a product or service for a transaction (or line item) B Item—SalesLineItem (or Sale)Flight—Reservation
A is a role related to a transaction B Customer—PaymentPassenger—Ticket
A is a physical or logical part of B Drawer—RegisterSquare—BoardSeat—Airplane
A is physically or logically contained in/on B Register—Store, Item—ShelfSquare—BoardPassenger—Airplane
A is a description for B ProductDescription—ItemFlightDescription—Flight
A is known/logged/recorded/reported/captured in B Sale—RegisterPiece—SquareReservation—FlightManifest
A is a member of B Cashier—StorePlayer—MonopolyGamePilot—Airline
A is an organizational subunit of B Department—StoreMaintenance—Airline
A uses or manages or owns B Cashier—RegisterPlayer—PiecePilot—Airplane
A is next to B SalesLineItem—SalesLineItemSquare—SquareCity—City

Of the above note the underlined High Priority Associations. Also don’t at this point go overboard with every conceivable association, stick to those that matter in your current iteration and focus. This whole exercise is about conveying meaning, don’t clutter you UML with noise.

Each end of an association is called a Role – and these can have names, multiplicity and navigability – all optional. Below some details on Multiplicity:

ScreenShot019

The standard naming convention for associations is TypeName-VerPhrase-TypeName – see the example above and stick to this format.

Finally CL dispenses a little gem of wisdom. Question is should DM be kept strictly up to date in future iterations as you discover new and interesting complexities or perhaps your requirements change? CL’s answer is – only if there is a practical real value to be gained from this. The purpose of DM is to convey knowledge and inspire later steps (namely our real Class Diagrams) – they are not a strict documentation tool!

Adding Attributes

Again CL tells us to focus on what we care about and what is important when adding these. Also focus on simple datatypes, anything beyond this is likely to be a conceptual object candidate in it’s own right. An example from the post traumatic world of CL:

ScreenShot020

If in doubt: define it as a separate conceptual class and avoid using FKs or overly trivial properties at this point, stick to what describes the Conceptual Class, things that describe the real world object we are working with. However – note also these  examples of seemingly simple data types which should really be conceptual classes are:

  • It is composed of separate sections: phone number, name of person
  • There are operations associated with it, such as parsing or validation: social security number
  • It has other attributes: promotional price could have a start (effective) date and end date
  • It is a quantity with a unit: payment amount has a unit of currency
  • It is an abstraction of one or more types with some of these qualities: item identifier in the sales domain is a generalization of types such as Universal Product Code (UPC) and European Article Number (EAN)

Now, a note on quantities. Most numeric quantities should not be represented as plain numbers – because it is a common requirement to know the unit and support conversions. So the attribute could perhaps be “quantity” and the unit “money” or the attribute is “width” and the unit is “centimeters” or “pixels” – what have you (you might want to convert pixels into print units). However, mapping each of these out into seperate classes called Quantity and Width is overkill, so what you do is collapse this information into the attribute, and you annotate these using “amount: money” or “width: pixels” – etc.
Basically, don’t just write a numerical attribute on it’s own, and be more specific than “number” or “int” when you define the unit. That’s all.

And that’s that!

OOA/D with UML and OO Patterns – Unified Process and Use Cases

This post is based on the 2nd Ed. of Craig Larman’s most excellent “Applying UML and Patterns”.

So this is going to be a fairly quick run-down of some of the core things to take away from the initial part of this book, dealing in particular with a reusable approach to identifying system requirements, risks and scopes – and more interestingly using use cases to build a foundation for our subsequent Object Oriented analysis of a business domain.

As I noted elsewhere I am reading the 2004 2nd edition of this book, so this book focuses on the “Unified Process” (UP) and only briefly mentions the newer SCRUM and Agile methodologies, however looking over the 3rd edition Larman tells us that the UP is a very open and flexible approach that is indeed very compatible with these newer working methodologies.

Let’sa kick off:

The Unified Process and Iterative Development

So you have probably heard this one before in some shape or form. What is the only constant in software development?
Change, is the answer. So, if  you’re going to plan, plan for change.

So what we should not do is come up with a huge rigid development specification and plan that sets out exacly what will be done when, but in stead apply an adaptive iterative process, where complexities are broken down, high risks are tackled one step at a time, and feedback from stakeholders is incorporated – all in a continuous upwards and organic cycle (our iterative process).
Really what you have to think of is the feeling that you don’t really understand something until you have done it, you don’t fully understand a problem until you have solved it, etc.

Some benefits of iterative development:

  • Early mitigation of high risks
  • Early visible progress
  • Early feedback from stakeholders
  • Better management of complexity (let’s just admit that we only have so much working memory, and tackle one set of problems at a time)
  • Lessons from each iteration can be applied to the next, so we have a self improving process (cue the violins around here)

How long is an iteration? Really depends on project, team size and what have you, but “Short is good” – find logical chunks and if in doubt, go for the shorter option.

Right – so how does this fit in with the UP? Well, let’s look at some tenants of UP:

  • Tackle high risk/value issues early.
  • Continuously engage stakeholders for feedback, evaluation and refinement of requirements.
  • Build a cohesive core architecture in early iterations.
  • Test early, often and realistically
  • Apply use cases
  • Model software visually (UML)
  • Carefully manage requirements
  • Carefully manage change requests

So reading through that you would probably agree when Larman says that this is compatible with Agile and SCRUM methodologies.

So what are the phases of the UP?

  1. Inception – this is a brief initial probing of the scope, vision and business case. Basically this is deciding whether to do an initial investigation – so we’re just testing the water here.
  2. Elaboration – thunderbirds are go! The project is a reality, and we now refine our vision, we identify most of the requirements and scoper and start an iterative implementation of the core architecture.
  3. Construction – iterative implementation of lower risks and more straightforward elements (thou the devil is of course always in the detail).
  4. Transition – beta test and deployment.

Despite this nicely laid out 1,2,3,4 list, Larman is keen to underline that this is not a conventional waterfall approach to development – each step (well at least 2 and 3) are iterative, and so contains x number of iterations where all the elements are repeated.

Also Larman briefly mentions an Agile UP – but this is just a kind of lightweight extra adaptive spin on the above, so we’re fly fucking about how you plan between iterations and such like. Key ideas is still to keep things light, plan for change, get feedback, test and adapt your planning and specification on a continuous basis.
Sounds great right? Sounds like a lot of meetings and a lot of emails if you ask me, but do realise that all projects have the potential for turning into an utter disaster, and being proactive and engaging your users and actually engaging yourself in the development process through systems like the UP or Agile/SCRUM is much less painful in the long run.
Can even be fun, but just don’t get too excited. This is still work, and there is a reason you’re paid to do it.

Now, let’s look at the old UP in a bit more detail:

FURPS+ Requirements Pattern

“FØRPS” – you can tell this is going to be good right. However, despite the name this or any other pattern you might find to your liking, is useful just to bear in mind.
Getting your requirements is of course important, and having a little check list like this to keep in mind is not a bad idea.

So – here they are (straight from he book (almost)):

  • Functional— features, capabilities, security.

  • Usability— human factors, help, documentation.

  • Reliability— frequency of failure, recoverability, predictability.

  • Performance— response times, throughput, accuracy, availability, resource usage.

  • Supportability— adaptability, maintainability, internationalization, configurability.

The “+” in FØRPS+ indicates ancillary and sub-factors, such as:

  • Implementation— resource limitations, languages and tools, hardware, …

  • Interface— constraints imposed by interfacing with external systems.

Great stuff – but do use it, will pay of.

Use Case Models

This one is important – and it’s actually a great tool if you use it the right way.

So first of all, use cases are just text that you write – so, in a sense this is not much of a “tool” – however, it’s the way that you do it that does it, so to speak.

So what you do is you write about important or key scenarios (sequence of actions or interactions) also known as a use case instance – and details what actors (person/user/computer system/organisation/3rd party interface, whatever) do to achieve a certain goal.

That last bit is important when trying to decide where to start with your use cases. Start by asking what are the main objectives of the actors in the domain, and don’t be afraid to start out quite general, i.e. “Customers want to buy products” – and then analyse this goal and break it down into more specific scenarios that you can write about in some meaningful level of detail. I.e. “Customers browse products online” and/or “Customer purchases products online”.

Another important aspect, especially for all you geeks out there, is to keep this simple and in a format that can be understood by all stakeholders, so don’t start worrying about technical details and implementation at this point. Keep it all at a high level of abstraction (aka Black-box style), with phrases like “System records the sale” but nothing about a databases being updated or similar.
Bear in mind the UP and the continuous feedback from your stakeholders (clients/users) in each iteration – Use Cases is an important tool that you can share with these, so make sure they are readable and also try not to make them overly convoluted or unnecessarily long.

Use Cases come in different formats:  brief, casual and fully dressed.
During Inception you might do a load of brief Use Cases and maybe 10-20% in fully dressed for high risk areas, and then during the elaboration iterations you will expand this to have fully dressed use cases for all important scenarios.

Within the fully dressed format, we have different formats as well, most noteworthy we have one that simply lists the flow of actions and another two-columns approach that separates user (human) actions on the left and system actions on the right. Larman prefers the first, I think I like the second.

Regardless of this, you should always use a format that includes:

  • Specify the primary actor.
  • List the stakeholders and their interests (goals) for the scenario.
  • Preconditions (what must happen before our scenario can start)’
  • Main Success scenario (in one or two column format)’
  • Extensions (alternative flows) – so for example some possible problems and how they should be handled.
  • Special requirements (any details that don’t fall into the above)’
  • Technology and Data Variations list (specific technical details (place here and not in main scenario description)).
  • Frequency of occurrence for the scenario (any time, monthly).
  • Open issues (things to be clarified and/or confirmed).

You can see an example template here: http://www.technosolutions.com/use_case_template.html which contains most (and some additional) of the above.

As a little aside I’ve (in my own personal capacity) started using AbstractSpoon’s wonderous ToDoList program for my Use Cases, using the Rich Text Editor in here you can start with general Use Cases and then sub these with more specific “Child Use Cases” as you go through the elaboration iterations – very useful – and also an absolute excellent time management programme! 5 out of 5!

Finally – let’s just touch on what is suitable for use cases. We’ll take this straight from the Larman’s mouth:

Use cases are defined to satisfy the goals of the primary actors. Hence, the basic procedure is:

  1. Choose the system boundary. Is it just a software application, the hardware and application as a unit, that plus a person using it, or an entire organization?
  2. Identify the primary actors—those that have goals fulfilled through using services of the system.
  3. Identify the goals for each primary actor.
  4. Define use cases that satisfy user goals; name them according to their goal.

Of course, in iterative and evolutionary development, not all goals or use cases will be fully or correctly identified near the start. It’s an evolving discovery.

Finally, Larman tells us to name use cases stating with a verb. So for example “Manage Users” or “Sell Product” etc.

Some other requirements for the Inception and Elaboration phase

A couple of good recommendations from Larman are:

Write a vision for the project – so record what the overall aim and purpose is (and keep your eyes on the price using this as you go meandering down the winding road of development).

Start a Glossary and keep this up to date (this is just an excellent idea, and especially for larger systems this becomes extremely valuable as people jump to and from the process).

Next up let’s have a look at System Sequence Diagrams (quick) and the Domain Model (in detail!).

Mr. Neal Ford gets Productive. Part 1: Accelerators

I spotted a Mr. Neal Ford doing a full day on the Microsoft DevWeek 2009 about ways to improve your productivity as a programmer. This appealed to me as it’s one of my new years semi-resolutions to get more done (too many ideas, not enough output).

Now it’s several hundred pounds to even attend a single DevDay – let alone a DevWeek – so I thought, bet this guy has some book that he is plugging, and bingo – on Safari (the excellent and searchable online IT library)  I found “The Productive Programmer – 1st Edition” by Mr. Neal Ford. Published July 08 (there’s the Amazon link for you as well). 

 Mr. Neal Ford it turns out does not come from a strict Microsoft background – and the book includes a lot of references to Java and Java IDE’s – also there are several references to Linux and the MAC OS – however, having said that there are plenty of good tips and tricks in this book for the Microsoft brainwashed, and it’s worth a read.

So without any further wibbling, some notes on Mr. Ford’s Amazing accelerators:

  • The general  thrust of this chapter is to improve the brain -> keyboard -> code flow. Main obstacles being clunky UI, the mouse (Mr. Ford does not like mice) and anything else that means your brain is preoccupied with the tool rather than the task.
  • A second important general principle is an emphasis on making an active effort to actually integrate these tools into your daily work, and doing this in a way that does not unnecessarily hamper your current productivity – but of course, no pain no gain.
  • So some of the more interesting  and .NET-centric tools mentioned – and let’s throw in a geek quiz, how many of these did you know:
    • Launching programmes rather than navigating – I personally use Launchy and can’t recommend it enough. Used to have about 18 quick launch icons, now I auto-hide the task bar (you will need the alt-tab extender mentioned below to really have fun with this).
    • Interestingly (and correctly I think) Mr. Ford does not recommend keyboard shortcuts for programmes – because these inevitably starts clashing with various programme short-cuts (especially in VS where the list of shortcuts is longer than your legs).
    • Tab completion in DOS and the Win explorer address bar – and ALT+D to access the win explorer address bar (and IExplore as well)
    • Clipboard history, copy a load, switch then paste a load. I installed and am now using the recommended CLCL – and it’s good, recommend it! One thing to note is that CLCL allows you to use keyboard shortcuts to paste from the clipboard list – but the num-pad keys do not work with this.
    • Mr. Ford like his command prompt, and sees this as more direct form of interaction with the OS. Couple of interesting gimmicks mentioned:  DOS up/down key for command history, I was not aware thatF7 allows you to actually navigate this (however shortcut keys do not work with F7, bit pants). Also I did not know that you can drag-and-drop files/folder from explorer into CMD to get the path.
    • The Windows Power Toys Alt+Tab Extender is recommended – allows you to navigate those +21 items that you always hit late in the afternoon after the 5th Project Manager (PM) has been over asking you for a quick favour. Also i found that setting the “Show full path in title” in the win explorer folder options works well with this as you can see the path wen tabbing through several Explorers.
    • Windows Power Toys Virtual Desktop is recommended. I am still making my mind up on this one. I can see it’s uses for the late afternoon scenario mentioned above – but it’s a bit of a smoke-and-mirrors tools as you are not really working on separate desktops (obviously, hence the virtual) but simple dividing the taskbar into separate sections. However, I can see it’s use in having a desktop for each task that you are juggling, so I guess I would have a desktop for each PM that I am working with, and then shoot number 5. It installs as a toolbar in your task pane, so enable it from here. I disabled the “Shared Desktops” option – the one limitation then is programs that do not allow multiple instances, these can of course only open in one of your VDs. But try it, it’s interesting.
    • The “Command Prompt Here” Win Power Toy is great – right click a folder and you have a CMD at that location.
    • An open source project “Command Prompt Explorer Bar” available from the excellent CodeProject site integrates the CMD into the bottom of your explorer window and follows your navigation.
    • Funny one – Mr. Ford claims using your programmes (and mainly IDEs I guess) in full screen mode saves mouse time, as you can simply ram your mouse to the top of the screen for the menu, rather than trying to click a specific menu. Bit like being back in the needle factory with Adam Smith really. One wonders how much Mr. Ford actually uses the mouse at all – but he has got a point, those milliseconds all add up, and at the end of the year you could have enough time saved to go and make yourself a cup of coffee.
    • Then we are into IDE shortcuts, learning and then actually making a conscious effort to use these. This is an old todo of mine – I used to have the VS2008 key map as my wallpaper. Funnily enough Mr. Ford actually recommends saying the short-cuts out loud as you use them to reinforce the memory – it does apparently work. 
    • Code Snippets is another one I need to pick up again myself.
    • Then we have recommendation to search rather than navigate when working in projects. Visual Studio gets neglected here so some of my recommendations: make sure you use the “go to definition” and “find all references” right clicks. Ctrl+shift+F is your next bet, but to speed up things you can actually use Google Desktop and the “open folder” feature quite easily (or live search if you’re that brainwashed). Also get used to the bookmarks for bits of code that you might return to.
    • Re-Sharper is mentioned. I liked this a lot, until I had to pay for it, then I stopped liking it. If anyone knows an open source alternative let us know!
    • Then we finish of with Macros, the main aim here is to create re-usable assets. You will of course find support in VS for these as well, thou I can’t say I’ve ever used one. Maybe I will add that as one of my goals for 2009. The excitement. For Windows the AutoHotKey is recommended.

With all these tools there is of course learning involved, and the recommendation is to do this in context, and one tool at a time.

Next in this series Mr. Neal Ford invites us to focus on what we are doing – so this is where we get the PM repellent out I hope.