Best Practices For Conducting Design Reviews

A lot of people would agree that design reviews can bring a lot of value to building quality software. However, when it comes to actually doing a design review we enter a somewhat blurry environment where everybody has another view on what a design is, how in-depth it should be etc, how it should be organised, etc.
Based on my own experience, I want to share the following tips and best practices with you :

1) Provide some overview material to the audience up-front. I want to stress the word 'overview material'; don't scare them off with implementation details.

2) Design reviews ask some discipline of the reviewers and in most cases a moderator comes in quite handy to make sure that you stay 'on target'. Although the 'official' character of the design review should not be exaggerated, it shouldn't become a coffee-chat neither.

3) Make it clear to everybody to 'be prepared'. People that didn't do their homework should not be attending or - at the very minimum - don't really have the right to speak. A moderator should be assigned to tackle such occurrences.

4) Requirements should be questioned during a review session of the requirements, not during a design review. Of course, for a good understanding the requirements should be explained properly (with a bit of background when required) prior to starting to talk about the solution. Mixing a discussion of the requirements and design is the best recipe for a long discussion without any added value.

5) A by-product of a design review is documentation. Independent of how 'agile' your team might be, it always comes in handy to have some form of documentation which can be used in the future to get an overview of what problem a certain design is solving and what te main concepts of the solution are.

6) Make sure that to stay at the right level of abstraction. The moderator should block implementation-detail discussions; instead he/she can take note of an action point to check what technology X or component Y could bring to the solution of the problem.

Finally, you should be aware of the danger of design reviews. One of the dangers is that the person responsible for the design starts making the design more complicated than it should be because he/she sees it as a way to demonstrate his/her technical capabilities to the audience. To migitate this risk, you should clearly communicate that complexity is only appreciated in case that there is no simple solution. Make sure that the addendees are also aware of this. In an environment where technical complexity is praised, nobody will even think of proposing a simple solution to a problem.

About the author

Mario Van Damme is a software architect, working for quite a number of years in the medical industry, and prior to that in the insurance and banking industry.
He can be contacted by e-mail at: mvandamme~AT~sopragroup.com and mario.vandamme.mv~AT~belgacom.net.

This is the direct link :

http://www.developerdotstar.com/mag/articles/oo_case.html

Note that it was publised already in July , but I was on a well deserved? :-) vacation.

I always found that connecting to an Oracle database is more diffucult than connecting with whatever other type of database.

This is mainly caused by the fact that you need to install the Oracle client software (aka SQL * NET client software) and configure it. You have to define the databases you want to connect to and because Oracle has its very specific terminology which on top of this changes from time to time it's much harder than it should be.

Oracle uses the TNSNAMES.ORA file to store the configuration data. This file is defined in an OOPS format, but there's also a configuration tool which is supposed to make life easier.

For those of you that don't want to know the inner details of Oracle, I want to share these tips.

Connecting to an Oracle 10g database using an Oracle 9 client

- To connect to an Oracle 10g database using an Oracle 9 client, you need to switch on the 'Use Oracle8 Release 8.0 Compatible identification' in the Oracle Net manager tool. Due to the fact that you are using an Oracle 9 client, this intuitively does not seem to be the way to do it.

Easy-connect

- As of Oracle 10g, a feature has been foreseen with the name 'Easy-connect'. 'Easy connect' and 'Oracle' in a positive sentence ? Indeed, as of Oracle 11, connecting to Oracle is as simple as connecting to SQL Server, DB/2 or whatever other type of database.
First of all, the - sometimes - problematic step of having to use the Oracle NET Manager is no longer required.
All you have to do is use the following syntax : 'sqlplus username/password@[//url] [:portnumber][/service Name]'.

Note that the two forward slashes are doing the magic here.

Some examples :
- sqlplus mario/password@//www.developerdotstar.com/MYSERVICE connects to the Oracle database residing on the - imaginary - www.developerdotstar.com server (the service MYSERVICE is listening on the default port 1521).

- sqlplus mario/password@//strike where 'strike' is the hostname of the PC on which the Oracle database is residing (the database service name is equal to the host name, which means that you don't need to specify it). Again, the database service is listening on port 1521.

- sqlplus mario/password@//strike:1700/DB1 where 'strike' is the hostname of the PC on which the Oracle database service DB1 is residing, listening on port 1700.

Some best-practices :

In the construction phase: when you are writing an application that needs to connect to an Oracle 10(+) database, you can use easy-connect in the early stages of development so save you from the burdon of having to do SQL*NET configuration work.

However, by the time you are about to release the first iteration of your application it should become configurable. You can do this easily by storing your connection string (preferably w/o user name and password) in a configuration file or in your configuration repository.

In the transition phase, it becomes important to think about how you'll connect to the database. Typically, the preference would be to use an alias (= logical name) instead of the name of a machine (physical name) and also to modify the default service name. For security reasons it's adviced not to use the standard Oracle port number 1521.

About the author

Mario Van Damme is a software architect, working for quite a number of years in the medical industry, and prior to that in the insurance and banking industry.
He can be contacted by e-mail at: mvandamme~AT~sopragroup.com and mario.vandamme.mv~AT~belgacom.net.

The problem was the following:
- You have a set of use cases and a large set of roles.
- The stakeholders are not only interested in the use cases as such, but they also want to see which role has which responsibility. In other words : Who can do what?

You could take up the minimum authorisation level in the preconditions of the different use cases, but this has as a drawback that you don't have any comprehensive overview.

So use cases are not sufficient. People with a requirements background tend to propose solutions which imply that you start introducing an actor per role and build huge inheritance trees of actors. You can see this illustrated in the following figure:

The drawback of this however is that this quickly becomes a whole mess if you have a huge number of roles.

Instead of trying to model everything using a use case diagram, the solution is to use a class diagram.
The idea I like to introduce is based on RBAC (Role Based Access Control). This is a simplified view :

Roles are made up of operations, which group functions.

The solution is to draw an object diagram (using a UML class diagram) and to create 'Function' objects that have a name that links to the UC (e.g. a function "Withdraw money " to refer to the "Withdraw money" use case).
If you feel that your use case names are not stable enough, then add a prefix (e.g. UC1) to uniquely identify the use case.

Next, you can create 'Role' objects that are referring (using an association relationship) to those functions. One such a role object can be "administrator" for example.

In case you have too many functions, group them into 'operations' and instead of drawing an object diagram with roles and functions, draw a object diagram with roles and operations.

Depending on the level of detail of the uses cases you'll either choose to refer to functions (level of detail : low) or operations (level of detail : high).

If you're afraid to create a spider web of relations between roles & functions (or operations), you can use different diagram instances where you model 3 roles per diagram for example (to make sure it's very readable and understandable).

When properly layed out, such diagrams can also be presented to your stakeholders. Roles and functions are a language they can understand.
This is a very simple example of such a diagram:

This is the most elegant solution, based on UML class diagrams and RBAC. It's not a good idea to model this using use case diagrams. UML has different diagrams, and nowhere it is written that you should be restrained to using use case diagrams when modeling requirements.

Martin Fowler's book on refactoring is a valuable piece, because it describes both phenomenea and cure. It also explains that refactoring is sometimes required to get to a stable code base. However, ever since his book has appeared a lot of people have been misusing the word on a frequent basis.

Martin Fowler's definition is the following:

"Refactoring is a disciplined technique for restructuring an existing body of code, altering its internal structure without changing its external behavior"

In its purest form, it's altering the internal structure without changing the external behaviour. Most often I hear the word 'refactoring' when people want to redesign a piece of software, when they want to write a whole new implementation, ... . As refactoring has the following connotation : 'it is a maintenance effort we cannot really escape from', it often gets accepted because it is well hidden under the cloak of 'refactoring'.

If it were not hidden under this cloak, people would have to answer more questions such as "why is this necessary", "what are the risks",...

I have heard the phrase "I've refactored the interface" being used a couple of times. This is actually in total contradiction with the real meaning of the word.

The problem is ofcourse : How we can cure this decease?

To do that, we should detect the symptoms : we should be triggered when somebody uses the word 'refactoring'. Instead of just accepting it, we should ask through in order to get an idea of the real nature of his/her request. To be able to do this, you should come to a situation where 'refactoring' ideas get announced prior to getting executed (for example in a short meeting or in a short stand-up meeting. Definitely not by e-mail but rather in face-to-face meetings).

The actual cure is that you need some form of sensibilisation of the associated risks of so-called 'refactoring' efforts together with a gatekeeper (or gatekeeper team) which will protect the system from unnecessary rework. I believe that creating business-awareness is a good way to tackle the decease : people should realise what the impact can be on the business. When they do, they'll already have a difficult time in convincing theirselves of the neccessity.

Also, you can more easily decrease the chance that people catch 'refactoritis' if there's enough work on their plate : When you have a tight schedule, people will automatically avoid unnecessary work (this is the human nature).

Many people don't worry about metadata; rather they are only interested in their data. However, metadata is extremely important as it describes the semantics of 'what' the data represents.

In this article, I'll briefly try to convince you of the importance of metadata. After that, I'll discuss some metadata approaches.

Why we need metadata

The red ribbon through this article is my example of digital pictures. When you look at these, at first sight there's no big difference in treating them in another way than any other file.

However, let's take a step back – outside of the digital era -. In the past, we all took pictures using a film camera and sent them to a film developer. The pictures that came out of the photo finisher would last many decennia.

In those days, we typically wrote some text on the back of the picture to indicate who was on there, where the picture was taken, and so on.

This type of 'data about data' is what we call metadata in computer science terms.

Metadata approaches

Metadata can be stored together with the data. An example of this is the JPEG format with its EXIF metadata header.

EXIF is a Japanese standard for storing exposure-related metadata.
These include: Exposure time, flash used y/n, camera manufacturer and model, lens used, etc.

The main advantage of this approach is the beauty of the 'self-containment' principle. This means that when you copy or move the file, the included metadata travels with it.

Another approach is to store the metadata in a separate file or repository. Tempting here is to use xml to describe this metadata. Note that also the semantic web falls into this category.

Physically separating the metadata from the data has the following advantages:

1. The file doesn't need to have a metadata header (Note that not all file formats have a metadata facility). File formats such as JPEG, MP3, MS-Word, etc. all have a metadata header. However, each file format has its own metadata standard.
2. The referenced file doesn't need to be altered in order to add metadata to it. Consider the situation where multiple people can add metadata to pictures on the web. Different people are evaluating the same picture differently (some will add metadata related to the colour composition, other related to the location, still others related to the exposure). In case this metadata would be stored into the file, it would be difficult in case of concurrent updates.
3. The metadata can be organised for faster access. Using indexes, etc it is possible to organise the metadata such that it can be accessed a lot more performant.
4. Metadata can also be added to files that don't include a metadata header.

A third approach is to keep the metadata in the files, while duplicating it in a separate repository outside the file. This brings the advantage of self-containment in combination with good performing querying capabilities. This approach is used in picture management software such as ASee/DSee.
The sad thing about it is that there is no standard storage format for this type of information.

Why should I be concerned

As I mentioned in the introduction with my example related to digital imaging, you typically want to keep images for multiple decennia.

We should be concerned about how we can make sure that we can still look at our digital pictures and their metadata many years from now.

So how can you backup your pictures with metadata?

• By copying the image files together with the specific tool 's metadata repository. The problem with this solution is that the tool's metadata repository (e.g. Kodak Easyshare software) is version-dependent and in a proprietary format. Do you think you will still be using the same software in ten years time? Or that this proprietary format will still be supported? Guess not.
• Write an index file containing metadata of the files in HTML format onto the media. Drawback: HTML is a presentation format, not good to be processed automatically.
• Write an index file containing metadata of the files in XML format onto the media. XML is a format that can be used for automatic processing later on, when there's a – hopefully – a standard way to duplicate the metadata.

Even though it's not ideal, I would advise to use the last option, by means of extracting the EXIF metadata header.

What would be the ideal situation?

• DVD players that are able to read, query and display the EXIF metadata. Windows XP currently doesn't show all EXIF metadata.
• A special media format for images (like ISO, UDF, etc), which is equally interpreted by DVD players and operating systems such as Windows XP.

You might wonder whether or not you will be able display your images after all those years (metadata without the data would not make sense, right).

To answer this, let's dive into the recent history:

GIF 87a is an image format that was created in 1987 and which is still supported on multiple platforms. It's almost 20 years old, so I definitely think that JPEG will last –at least – as long as the GIF format.

Extending the EXIF metadata

The EXIF metadata can be extended in many ways:

An example of such as extension is the ability to add the GPS coordinates to the image's exif metadata header when you are taking a picture. With GPS becoming a commodity, prices are dropping tremendously; it doesn't have to take long before some vendor of digital cameras sees this as a competitive feature.

Can you imagine? You travel around for a couple of weeks, visit some places and take a lot of pictures. You come home, and there your PC software is able to link the location of where you took each picture, based on the GPS coordinates in the EXIF metadata.

Another example is the weather: You are looking at a picture; it looks warm but how warm was it? This could be accomplished in one of the following ways:

1. Indirectly using the GPS coordinates together with the date/time that the picture was taken.
2. Directly by incorporating a thermometer into the digital camera, storing the result in the EXIF metadata.

Metadata rules

Let me end with some metadata rules:

1. Don't misuse the semantics of metadata fields.
   In the context of the EXIF standard and what Windows XP shows you be default, it might be tempting to misuse the 'Model make' (manufacturer of the device that captured the image) to put in your own comments for example. This field is shown be default, so you always have access to your comments when using the Windows Explorer.
2. The metadata standard used needs to be extensible. You can add additional metadata fields to the EXIF format for example.

Resources on EXIF metadata

1. The unofficial EXIF site : http://www.exif.org
2. EXIF reader : http://www.takenet.or.jp/~ryuuji/minisoft/exifread/english/
3. .NET API : http://www.eggheadcafe.com/articles/20030706.asp
4. Java API : http://sourceforge.net/projects/libexif

Exif command line tool (examples):

1. exiv2.exe -M"add Exif.Image.Make Mario" "D:\Documents and Settings\All Users\Documents\My Pictures\Winter.jpg" : Add the image creator
2. exiv2.exe -M"ADD EXIF.PHOTO.USERCOMMENT THIS PICTURE WAS TAKEN IN THE WINTER." "D:\DOCUMENTS AND SETTINGS\ALL USERS\DOCUMENTS\MY PICTURES\WINTER.JPG" : Add user comment

About the author

Mario Van Damme is a software architect, working for quite a number of years in the medical industry, and prior to that in the insurance and banking industry.
He can be contacted by e-mail at: mvandamme@sopragroup.com and mario.vandamme.mv@belgacom.net.

1 INTRODUCTION
Assertions are contracts, just as Bertrand Meyer already stated several years ago. A lot has been written already on assertions: from assertion styleguides to aspect-oriented frameworks for managing preconditions.

One of the base principles of contracts – in real life as well as in software – is the fact that it cannot be modified uni-lateraly.

For software, this implies that you cannot make your pre-conditions of your interface methods more strict all of a sudden when releasing a new version of a component.

Therefore, make sure to think upfront: The better you have thought everything through, the less contract re-negociations you will have to make in the future.
In this article, I’m using a real-life example to demonstrate the seriousness of what is – at first sight – an implementation detail.

2 A REAL-LIFE EXAMPLE

A general component which provides the implementation of a crosscutting concern is updated with extra precondition checks. Why? With the best intentions, the author of the component suddenly realised that he had forgotten to check some preconditions.

Without any further communication, the component is adapted and gets released. Of course, with the extreme programming thought in mind he also makes sure that all of his unit test work well.

Having received a new version of the software – which was just a ‘maintenance’ release by the way –, one of the applications which uses this component tries to integrate it. The integration goes seamlessly, as at first sight no ‘breaking’ changes have been made.

This is where the catch lies: In case an interface method would have been modified ‘by accident’, this would have been detected at compile-time when integrating. Integration would then be stopped prior to give an official ‘go’.

The people working on the application can run their unit tests and they – most likely – will just run. When they’re lucky the tests will fail on the extra precondition check. In a data driven environment, chances are low.

So when does this extra assertion pop up?
Of course, Murphy’s law pops up here: you can be sure of it that it will pop up at the least convenient time. As the problem can only be detected at run-time and nobody is really aware of this extra precondition it will escape the attention of both the development and QA department.

In a worst case scenario, you will see it at the customer site (when you are writing customer software), when you are giving a demo, etc. And this costs!

3 CONCLUSION
Use assertions wisely; go back to the essence of design by contract and treat every change to an assertion as a change to the contract. Secondly, make sure that your ‘contract’ is properly documented and that everybody that is involved is up to date.

REFERENCES
[Meyer88] Bertrand Meyer: “Object-Oriented Software Construction”, Prentice Hall, 1988.

About the author
Mario Van Damme is a software architect, working for quite a number of years in the medical industry, and prior to that in the insurance and banking industry.
He can be contacted by e-mail at: mvandamme@sopragroup.com and mario.vandamme.mv@belgacom.net.