Software Engineering » Eric Feminella

Let design guide, not dictate

A good design should be intended to guide implementation, not dictate it; and for good reason as in the real world of software development requirements and systems are far to complex and dynamic in nature to view a technical design as anything more than a basic prescription intended to form the basis of an efficient implementation. Yet far too often many people seem to believe that once a detailed design has been completed and approved implementation should be a breeze; however, this is just not a very realistic expectation.

For instance, one of my core job responsibilities is to review technical design documents and provide feedback and direction. This is an iterative process which typically has between 1-3 iterations depending on the complexity of the system. Initially myself and an engineer are given requirements for review. He or she then begins an initial draft of the design and once completed passes it on to me for review. I then review the document and provide feedback where applicable, either via annotations to the document itself or by reviewing with the developer (which is by far my preferred process). Should modifications be required the developer will then make revisions as needed. This process is repeated (within practicality) until final design has been approved.

At first it may appear as if only a single design iteration and review would be needed, however more often than not, requirements may not be completely understood during the beginning stages of design, nor are they typically ever set in stone so it is very common that a design will need to change during the early stages of a project or even throughout the entire development stage. Once final design has been completed an engineer then begins implementing the design. Theoretically this may appear to be a quite simple process: create a great design which contains as much detail as possible, review it, make revisions and approve it, then just pass it off to any developer for implementation and thatâ€™s it, done, right? – wrong!

There are a number of problems to this approach. Below I have outlined the three I feel are most significant and the solutions I have found to address each.

Creativity
The first problem is that a design which goes into too much detail completely limits or even worse, kills creativity – which in my opinion is the single most important trait a developer can possess, especially when designing. The developer is now merely a typist and will undoubtedly become very bored when implementing the design, especially if it is not even his/her design to begin with! Because of this lack of creativity the final code will ultimately suffer and bugs can be expected. Keeping design on a higher level allows developers to have the creative freedom needed to provide quality implementations and work they can feel is their own.

Flexibility
The second problem is that the more detailed and precise the design the less flexibility there is when requirements change and modifications need to be made to the design and thus implementation. For example, if a design contains very low level details, such as method signatures and other implementation specific details the ability to change the design now becomes increasingly complex and will result in much of the design needing to be reworked significantly. In addition the more detail there is the harder it is to write unit tests against the design as the actual implementation has already been defined. Designs need to be very high level and should not go beyond identifying class names, their responsibilities, relationships and dependencies.

Tools
The third problem is that far too often developers get caught up in all the details of UML notation and related tools. Again, this negates creativity and results in the developer concentrating more on making the design look technically correct rather than concentrating on designing towards a great solution which addresses the problem at hand. In addition, this also results in unnecessary time being spent to complete the design – time which otherwise could have been much better spent on something that produces a better pay off for the project. Now this is not to say that UML shouldn’t be used, actually quite the contrary as I feel a final design should be in UML (or some other format) as a shared language is very helpful in allowing readers to easily understand the design. I always suggest a technique where developers draw out their design in any way that makes sense to them without having to give much thought to anything other than the solution itself. This could be anything from drawing / scribbling thoughts on a pad, to building out a vision from legos – seriously! Only once the design has been envisioned would I recommend bringing it to realization through the use of a formal design tool, such as Visio or other UML tools to be used.

The above illustrates the three most common design issues I have encountered, most of which pertain to over-detailed designs, as well as the approach I take to address each. If you have not encountered any of these issues in your own work than that is generally a good sign, however try to keep them in mind when designing as it will pay off in the end. The important thing to remember when designing is to design for flexibility and simplicity. Less is usually more and the KISS principle, especially when applied to software design, will always pay off in the end.

4 comments

Package-level function closures in ActionScript

Package-level function closures are very useful for creating generalized functionality which does not require a class (static methods) or instance of a class (instance methods).

Unlike static and instance methods package-level function closures are not associated with a class or instance of a class but rather with a package. There are no syntactical differences between package-level functions and static or instance methods.

Package-level functions are for the most part utility functions; for instance the flash.utils package contains a number of package-level functions, the most common of which are describeType(), getDefintionByName(), getTimer() and so forth.

Package-level function closures are created by defining a function directly inside the body of a package (where class and interfaces are defined), as can be seen in the following example:


package com.ericfeminella.display
{
import flash.display.Bitmap;
import flash.display.IBitmapDrawable;
import mx.graphics.ImageSnapshot;
        
public function createSnapShot(target:IBitmapDrawable) : Bitmap 
{
    return new Bitmap( ImageSnapshot.captureBitmapData( target ) );
}
}

package com.ericfeminella.display

{

import flash.display.Bitmap;

import flash.display.IBitmapDrawable;

import mx.graphics.ImageSnapshot;

public function createSnapShot(target:IBitmapDrawable) : Bitmap

{

return new Bitmap( ImageSnapshot.captureBitmapData( target ) );

}

Calling a package level function is straightforward, simply import the function just as you would a class or interface and then invoke the function directly…


// import package function
import com.ericfeminella.display.createSnapShot;

// once imported the function can be invoked
createSnapShot( this );

// import package function

import com.ericfeminella.display.createSnapShot;

// once imported the function can be invoked

createSnapShot( this );

Typically you will find that most functionality can be grouped to a Class or an instance object, however on occasion you may identify specific functionality which is common to packaged functionality as opposed to a specific object, and in these cases utilizing package-level functions is a great option.

May 6, 2008 Object Oriented Design / Software Engineering

11 comments

Web-Based UML Sequence Diagram Generator

If you need to create sequence diagrams quickly and do not have the time to use the more traditional Software Modeling tools; Together, Enterprise Architect, Visio etc. you should take a look at www.websequencediagrams.com.

This handy little tool is pretty capable for a free web based utility and is very easy to use. It took me just seconds to create the simple sequence diagram below…

Web-Based UML Sequence Diagram Generator

So the next time you need to create UML sequence diagrams in a hurry make sure to check out this very useful tool.

April 14, 2008 Agile / Software Engineering

2 comments

Principle of Least Knowledge

One very important (yet often overlooked) design guideline which I advocate is the Principle of least knowledge.

The Principle of Least knowledge, also known as The law of Demeter, or more precisely, the Law of Demeter for Functions/Methods (LoD-F) is a design principle which provides guidelines for designing a system with minimal dependencies. It is typically summarized as “Only talk to your immediate friends.”

What this means is a client should only have knowledge of an objects members, and not have access to properties and methods of other objects via the members. To put it in simple terms you should only have access to the members of the object, and nothing beyond that. Think if it like this: if you use more than 1 dot you are violating the principle.

Consider the following: We have three classes: ClassA, ClassB and ClassC. ClassA has an instance member of type ClassB. ClassB has an instance member of type ClassC. This can be designed in such a way which allows direct access all the way down the dependency chain to ClassC or beyond, as in the following example:


// ClassA defines a member of type ClassB and provides
// access to the instance
public class ClassA
{
    private var b:ClassB;
    
    public function getB() : ClassB
    {
         return b;
    }
}

// ClassB defines a member of type ClassC and provides 
// access to the instance
public class ClassB
{
    private var c:ClassC = new ClassC();
    
    public function getC() : ClassC 
    {
         return c;
    }
}

// ClassC could expose additional members and on and 
// on creating more and more direct dependencies
public class ClassC
{
    public someType:SomeType;
    ...
}

// client implementation
var a:ClassA = new ClassA();
var sometype:SomeType = a.getB().getC().someType;

// ClassA defines a member of type ClassB and provides

// access to the instance

public class ClassA

{

private var b:ClassB;

public function getB() : ClassB

{

return b;

}

// ClassB defines a member of type ClassC and provides

// access to the instance

public class ClassB

{

private var c:ClassC = new ClassC();

public function getC() : ClassC

{

return c;

}

// ClassC could expose additional members and on and

// on creating more and more direct dependencies

public class ClassC

{

public someType:SomeType;

...

}

// client implementation

var a:ClassA = new ClassA();

var sometype:SomeType = a.getB().getC().someType;

The above example is quite common, however it violates The Principle of Least Knowledge as it creates multiple dependencies, thus reducing maintainability as should the internal structure of ClassA need to change so would all instances of ClassA.

Now keep in mind that in all software development there are trade-offs to some degree. Sometimes performance trumps maintainability or vice-versa, other times readability trumps both. A perfect example of where you would not want to use The Principle of Least Knowledge is in a Cairngorm ModelLocator implementation. The Cairngorm ModelLocator violates the Principle of least knowledge for good reason – it simply would not be practical to write wrapper methods for every object on the ModelLocator. This is the main drawback of the Principle of least Knowledge; the need to create wrapper methods for each object, which are more formally known as Demeter Transmogrifiers.

The goal of good software design is to minimize dependencies, and by carefully following the guidelines provided by The Principle of Least Knowledge this becomes much easier to accomplish.

February 2, 2008 Agile / Code Review / Design Patterns / News / Object Oriented Design / Software Engineering

1 comment

Flex Unit TestSuiteHelper

Test Driven Development is an essential part of any software project. Leveraging Flex Unit in your Flex and AIR projects is a well known best practice and will inevitably result in less unknowns and provide a much more reliable codebase, however like most things in life that provide value, unit testing comes at a cost: Time.

In general, writing Unit tests is often an overlooked process as it ultimately equates to an additional level of effort (time) in a project plan. However, writing unit tests should not be over looked for a number of reasons, and in my opinion most importantly because it forces developers to understand what problems the code they write are intended to solve, thus resulting in a better understanding of the problem domain.

Now without getting into a lengthy discussion about the benefits of Test Driven Development, as there is plenty of information available on the subject, I am going to focus on how to make it easier in Flex.

Typically when I write a unit test I stub it out and then run the test runner to make sure it fails. I pretty much do this immediately after I write the test and then I see that my test did not come up and realize I never added it to the test suite. Obviously something like adding tests to a test suite can be an automated process which would allow unit tests to be developed a little faster as all that would be needed was to write the test.

So in an effort to simplify the process of adding tests to a test suite I have developed a TestSuiteHelper which is a simple utility class that automates the process of adding unit tests to a test suite. Rather than manually adding each test the TestSuiteHelper will automate the process simply by invoking a static method and passing in the test class from which you need to extract all of the tests.

So if you would like to simplify your teamâ€™s unit testing workflow feel free to utilize the TestSuiteHelper.

January 18, 2008 Agile / Software Engineering / Test Driven Development

4 comments

API Design: Method parameter objects

When defining a constructor or method with more than three parameters it is considered a best practice to create a parameters object for holding the values which are required. This especially holds true when some of the parameters are optional (as they will contain default values) and also when two or more consecutive parameters are of the same type (as developers may accidentally transpose these parameters – which will not result in compile time or runtime errors, making debugging a nightmare!)

The most appropriate solution for such cases is to break up the method into separate methods, however when this is not feasible creating a parameters object will improve both code readability and provide a cleaner design which leaves less room for unexpected errors.

Consider the following method:


public function someMethod(a:String, 
                           b:Object, 
                           c:int = 1, 
                           x:int = 2, 
                           y:int = 3, 
                           z:Boolean = true):SomeType 
{

public function someMethod(a:String,

b:Object,

c:int = 1,

x:int = 2,

y:int = 3,

z:Boolean = true):SomeType

{

The parameters defined in this method are typical of what you will often see, however it is much cleaner and reliable to create a parameters object for holding these parameters. In addition, a parameters object allows for a much easier client implementation as default values need not be reassigned for all parameters which proceed a parameter which you need to specify a value other than the default value. For instance, if a method accepts 5 parameters and the first two parameters are required but the last three are optional, if you you need to specify a value for the last parameter you will need to re-assign the default values for the proceeding parameters, when in fact you really only need to specify three parameters.

The following example demonstrates creating a parameter object which can be passed to “someMethod”:


package
{
    public final class SomeMethodParams
    {
      public var a:String; 
      public var b:Object; 
      public var c:int = 1; 
      public var x:int = 2; 
      public var y:int = 3;
      public var z:Boolean = true;
        
      //only specify required parameters in constructor
      //optional parameters are simply public properties
      //which have default values assigned
      public function SomeMethodParams(a:String, b:Object)
      {
          this.a = a;
          this.b = b;
      }   
   }
}

package

{

public final class SomeMethodParams

{

public var a:String;

public var b:Object;

public var c:int = 1;

public var x:int = 2;

public var y:int = 3;

public var z:Boolean = true;

//only specify required parameters in constructor

//optional parameters are simply public properties

//which have default values assigned

public function SomeMethodParams(a:String, b:Object)

{

this.a = a;

this.b = b;

}

When invoking â€œsomeMethodâ€ clients can now simply instantiate an instance of the parameter object, set values only for what is needed and pass it in as follows:


var params:SomeMethodParams= new SomeMethodParams("a",{}) ;
params.z = false;

instance.someMethod( params );

var params:SomeMethodParams= new SomeMethodParams("a",{}) ;

params.z = false;

instance.someMethod( params );

So if you would like to improved code readability and provide proactive exception precautions, consider utilizing parameter objects for methods which require more than three parameters.

January 12, 2008 Agile / Code Review / Design Patterns / Object Oriented Design / Software Engineering

2 comments

Using Namespaces to provide context in AS3

Namespaces in ActionScript 3 are particularly useful for providing context in an application. They also provide an added clarity to APIs outside of the typical language specific access modifiers.

For instance, let’s say we have an application which requires slightly different behaviors depending on a specific type of user. If the user is a guest, the application need only display a fairly basic view, however, if the user is an administrator the application must display a slightly more complex view.

Based on the type of user we can deduce context and from this context we can provide a contextual namespace. The contextual namespace can then be utilized to invoke different methods with the same name on an object.

To help facilitate the management of a contextual namespace I have created a ContextNamespace API.

ContextNamespace is a Singleton class which can be utilized to set and retrieve a contextual namespace based on context. Additionally, ContextNamespace implements INamespaceManager which defines various convenience methods for retrieving information about a contextual namespace, comparing a Namespace against the contextual Namespace and comparing a URI against the contextual Namespace URI.

Below is a simple example which demonstrates how to utilize the ContextNamespace API.

The class below utilizes two custom namespaces; admin and guest. Two methods with the same name are defined in the Class, each of which is under a different namespace.

package
{
    import com.domain.namespaces.admin;
    import com.domain.namespaces.guest;
  
    public class UserViewHelper
    {
        // define the admin implementation of renderView
        admin static function renderView() : void
        {
            // admin implementation code...
        }

        // define the guest implementation of renderView
        guest static function renderView() : void 
        {
            // guest implementation code...
        }
    }
}

package

{

import com.domain.namespaces.admin;

import com.domain.namespaces.guest;

public class UserViewHelper

{

// define the admin implementation of renderView

admin static function renderView() : void

{

// admin implementation code...

}

// define the guest implementation of renderView

guest static function renderView() : void

{

// guest implementation code...

}

To utilize ContextNamespace to retrieve a reference to the current contextual Namespace is simple.


import com.ericfeminella.ns.ContextNamespace;

// define a local namespace object
var ns:Namespace; 

// reference the contextual namespace
ns = ContextNamespace.instance.getNamespace();

// invoke methods using the namespace reference
// should the contextual namespace change the
// implementation will reflect the change
UserViewHelper.ns::renderView();

import com.ericfeminella.ns.ContextNamespace;

// define a local namespace object

var ns:Namespace;

// reference the contextual namespace

ns = ContextNamespace.instance.getNamespace();

// invoke methods using the namespace reference

// should the contextual namespace change the

// implementation will reflect the change

UserViewHelper.ns::renderView();

In the above code a local namespace is defined which references the current contextual namespace used by the application via ContextNamespace.instance.getNamespace(). The local reference is then used to identify the correct namespace from which methods are to be invoked.

For additional examples which demonstrate how ContextNamespace can be utilized to provide a globally accessible reference to a namespace, view the ASDocs.

ASDocs
ContextNamespace
INamespaceManager

December 17, 2007 Software Engineering

Comments Off

Measuring code performance in ActionScript 3

Adobe Flex 3 introduces the much needed, and highly welcomed Flex Profiler which allows Flex and AIR application to be thoroughly examined to measure code performance and determine potential so called “memory leaks” (not that such a thing exists – it’s called a programming error, but that’s a whole other subject in itself). Flex 3.0 provides a new profiling perspective which contains all of the tools one might expect from a high quality profiling utility. I highly recommend taking advantage of the profiler and utilizing it as a powerful addition to your Flex workflow.

Even with all of the great features available in the Profiler I still find it useful to have the ability to monitor code performance in ActionScript, especially when determining the elapsed duration of service invocations. With this in mind I developed a simple API which allows developers to measure the performance of their code as it executes; such as loops, method invocations, service invocations and so forth.

The Execution class provides an intuitive API (defined by IExecutable) from which the elapsed time of a code execution, as well as the total duration of a code execution can be measured. This can be accomplished in as little as 2 lines of code. The underlying implementation is simple and the higher level API makes it easy to use.

Typically developers should utilize the Execution API as a development aid as it is intended for use in dev environments. All references should be removed prior to an actual prod release as there is no need to compile the code into your release swf.

Below I have provided links to the Execution API resources as well as documentation which contains comprehensive use-case examples.

Execution API
IExecutable
Execution

November 3, 2007 Software Engineering

Comments Off

Configurable ContextMenu API update / example

I have received numerous requests for an example which demonstrates how to implement the ConfigurableContextMenu API which I had developed back in February of this year.

In the time since the original post I have re-factored many of the core features, however the goal of the ConfigurableContextMenu API remains the same.

The following is a brief recap from the original post.

The ContextMenu classes in ActionScript 3: ContextMenu, ContextMenuItem, ContextMenuBuiltInItems provide a good base for working with context menus in Flex 2, however they do not provide an intuitive API for developing and working with custom context menus, especially at runtime, so in this regard these classes fall short to some degree.

In order to provide a solution which addresses the issues mentioned above I have developed a ConfigurableContextMenu API which allows developers to dynamically create custom context menus by which items can be added, removed, enabled, disabled, shown, hidden and cloned dynamically at runtime. This API also addresses certain Flash Player restrictions which fail silently in the ContextMenuItem class such as caption collisions and reserved captions restrictions which are simply ignored by Flash Player, leaving the developer clueless (until reading the documentation) as to why the items have not been created.

Below I have provided links to ConfigurableContextMenu resources which include complete documentation, UML class diagrams and basic example Flex application.

example
asdoc
uml diagram

The ConfigurableContextMenu API is published under the MIT license.

October 28, 2007 News / Object Oriented Design / Software Engineering

2 comments

MD5, SHA1 and SHA-256 Encryption Utility

If you work with different types of encrypted data it is often quite useful to have a utility available from which you can utilize to encrypt a String to a specific encryption format.

I find it particularly useful to isolate each available encryption object into a single Helper / Utility class to help facilitate encryption requests; essentially providing a wrapper for all encryption objects.

The Encryption utility is an all static class which is intended to provide a solution for centralizing access to encryption classes. The Encryption utility simply wraps all encryption types available in a Flex Application and provides a single static method for encrypting a String to the specified encryption type.

Additionally, the Encryption utility provides constants which represent each supported encryption type; SHA-256, SHA1 and MD5.

Using the Encryption utility is simple and straightforward as one might expect. The following examples demonstrate a typical use-case in which a String; “test”, is encrypted utilizing each defined encryption type:


trace(Encryption.encrypt("test",Encryption.CRYPTO_SHA256));
//df3f619804a92fdb4057192dc43dd748ea778adc52bc498ce80524c014b8
//1119

trace(Encryption.encrypt("test",Encryption.CRYPTO_SHA1));
//a94a8fe5ccb19ba61c4c0873d391e987982fbbd3

trace(Encryption.encrypt("test",Encryption.CRYPTO_MD5));
//098f6bcd4621d373cade4e832627b4f6

trace(Encryption.encrypt("test",Encryption.CRYPTO_SHA256));

//df3f619804a92fdb4057192dc43dd748ea778adc52bc498ce80524c014b8

//1119

trace(Encryption.encrypt("test",Encryption.CRYPTO_SHA1));

//a94a8fe5ccb19ba61c4c0873d391e987982fbbd3

trace(Encryption.encrypt("test",Encryption.CRYPTO_MD5));

//098f6bcd4621d373cade4e832627b4f6

So if you need an easy to use, centralized location from which you can conveniently call up to encrypt a String, feel free to utilize the Encryption utility.

The Encryption utility is protected under the MIT license.

October 6, 2007 Software Engineering

Comments Off