You are currently browsing the archives for the Software Engineering category

Misplaced Code

Often I come across what I like to call “Misplaced Code”, that is, code which should be refactored to a specific, independent concern rather than mistakenly being defined in an incorrect context.

For instance, consider the following example to get a better idea of what I mean:

var url:String = Application.application.url;

if ( url.indexOf( "localhost" ) {
…
} else if ( url.indexOf( "dev" ){
…
} else if ( url.indexOf( "staging" ){
…
}
etc…

Taking the above example into a broader context, it is quite common to see code such as this scattered throughout a codebase; particularly in the context of view concerns. At best this could become hard to maintain and, at worst, it will result in unexpected bugs down the road. In most cases (as in the above example) the actual code itself is not necessarily bad, however it is the context in which it is placed which is what I would like to highlight as it will almost certainly cause technical debt to some extent.

Considering the above example, should code such as this become redundantly implemented throughout a codebase it is quite easy to see how it can become a maintenance issue as, something as simple as a change to a hostname would require multiple refactorings. A much more appropriate solution would be to encapsulate this logic within a specific class whose purpose is to provide a facility from which this information can be determined. In this manner unnecessary redundancy would be eliminated (as well as risk) and valuable development time would be regained as the code would need only be tested and written once – in one place.

So again, using the above example, this could be refactored to a specific API and client code would leverage the API as in the following:

switch( DeploymentContext.host )
{
    case DeploymentContext.LOCAL_HOST :
         …
         break;
    case DeploymentContext.DEV:
         …
         break;
    case DeploymentContext.STAGING:
         …
         break;
}

This may appear quite straightforward, however, I have seen examples (this one in particular) in numerous projects over the years and it is worth pointing out. Always take the context to which code is placed into consideration and you will reap the maintenance benefits in the long run.

May 31, 2010 Agile / Code Review / Design Patterns / Object Oriented Design / Refactoring / Software Engineering / Test Driven Development
1 comment

Simple RPC Instrumentation in Flex

On occasion developers may find a need to quickly measure the time it takes for a request to a remote service to return a response back to the client without the need to employ an automated testing tool to perform the instrumentation. This information can prove quite valuable for performing application diagnostics on the client and, when measured in terms of code execution, monitoring at the execution level will always be a bit more precise than that which can be measured by using a Network proxy alone, such as Charles or Fiddler, etc.

Obviously there are numerous solutions which can be implemented to monitor the elapsed time of a service invocation, however it was my goal to provide a unified solution which could easily be implemented into existing client code without significant refactorings being required.

In order to achieve this I first needed to consider what the typical implementation of a service invocation is in order to isolate the
commonality. From there it is only a matter of determining a solution that meets the objective in the most non intrusive manner possible.

To begin let us consider what a “typical” service invocation might look like for the three most common services available in the Flex Framework; HTTPService, RemoteObject and WebService.

// HTTPService
var call:AsyncToken = service.send(…);
call.addResponder( this );

// RemoteObject
var call:AsyncToken = service.someMethod(…);
call.addResponder( this );

// WebService
var call:AsyncToken = service.someOperation(…);
call.addResponder( this );
 

Based on the 3 above implementations we can deduce that the common API used when performing a service invocation is AsyncToken. So to provide a unified solution for all three common Services we could either extend AsyncToken or provider an API which wraps AsyncToken. For my needs I chose to implement an API which simply monitors an AsyncToken from which the duration of an invocation can be determined, thus I wrote an RPCDiagnostics API which can be “plugged” into an AsyncToken client implementation.

RPCDiagnostics provides basic performance analysis of a Remote Procedure Call by providing a message which displays information about the operation duration via a standard trace call. In addition, an event listener of type RPCDiagnosticsEvent can be added to facilitate custom diagnostics and Logging.

RPCDiagnostics can easily be implemented as an addition to an existing AsyncToken or in place of an AsyncToken. The following examples demonstrate both implementations.

Implementing RPCDiagnostics onto an existing AsyncToken:

var call:AsyncToken = null;
call = RPCDiagnostics.monitorToken(service.send(),"methodName");
call.addResponder( … );
 

Implementing RPCDiagnostics in place of an AsyncToken:

var call:RPCDiagnostics = null;
call = new RPCDiagnostics( service.send(), "methodName" );
call.addResponder( … );
 

Implementing a listener to an RPCDiagnostics instance:

var call:RPCDiagnostics = null;
call = new RPCDiagnostics( service.send(), "operationName" );
call.addResponder( … );
call.addEventListener( RPCDiagnosticsEvent.EXECUTION_COMPLETE,
                       handler);
 

The RPCDiagnostics API and dependencies can be downloaded via the Open Source AS3 APIs page or from the below links:

RPCDiagnostics
RPCDiagnosticsEvent
Execution

September 20, 2009 APIs / Object Oriented Design / Software Engineering
No comments

Design Considerations: Naming Conventions

Intuitive naming conventions are perhaps one of the most important factors in providing a scalable software system. They are essential to ensuring an Object Oriented System can easily be understood, and thus modified by all members of a team regardless of their tenure within the organization or individual experience level.

When classes, interfaces, methods, properties, identifiers, events and the like fail to follow logical, consistent and intuitive naming conventions the resulting software becomes significantly more complex to understand, follow and maintain. As such this makes changes much more challenging than they would have been had better naming been considered originally. Of equal concern is the inevitability that poor naming will lead to redundant code being scattered throughout a project as when the intent of code is not clearly conveyed with as little thought as possible developers tend to re-implement existing functionality when the needed API cannot easily be located or identified.

Code is typically read many, many more times than it is written. With this in mind it is important to understand that the goal of good naming is to be as clear and concise as possible so that a reader of the code can easily determine the codes intent and purpose; just by reading it.

Teams should collectively define a set of standard naming conventions which align well with the typical conventions found in their language of choice. In doing so this will help to avoid arbitrary naming conventions which often result in code that is significantly harder to determine intent, and thus maintain. Of equal importance is the need for various teams from within the same engineering department to standardize on domain specific terms which align with the non-technical terms used by business stakeholders. Together this will help to develop a shared lexicon between business owners and engineers, and allow for simplified analysis of requirements etc.

Ideally, code should follow the PIE Principle (Program, Intently and expressively) – that is, code should clearly convey purpose and intent. In doing so the ability to maintain a software application over time becomes significantly easier and limits the possibility of introducing potential risk to project deliverables.

In short, conventions are very important regardless of a teams size; beit a large collaborative team environment, or a single developer who only deals with his own code. Consistency and conventions are a key aspect to ensuring code quality.

July 31, 2009 Agile / Code Review / Object Oriented Design / Refactoring / Software Engineering
1 comment

What makes a good design?

One of my core job responsibilities for the past several years has been to conduct technical design and implementation (code) reviews during various phases of the software development life cycle. This is typically a highly collaborative process whereas myself and an individual engineer, or the team as a whole will begin by performing a detailed analysis of business requirements in order to gain an initial understanding of the specific component(s) being developed. Once an understanding of the requirements has been reached a brainstorming session ensues which ultimately leads to various creative, technical solutions. After discussing the pros and cons of each the best solutions quickly begin to reveal themselves, at which point it is simply a process of elimination until the most appropriate solution has surfaced.

The next step is to translate the requirements into the proposed technical solution in the form of a design document. The design is specified on a high level and is only intended to provide an overview of the appropriate technical road map which is to be implemented. This typically consists of higher level UML Sequence and Class diagrams, either in the form of actual diagrams produced in a UML editor, or could simply be a picture captured from UML drawn out during a whiteboarding session. The formality of the documented design is less important, what is important is that the design is captured in some form before it is implemented. Implementation specific details such as exact class and method signatures and so forth are intentionally left out as they are to be considered outside the scope of the design. See Let Design Guide, not Dictate for more on this subject. Once the design is documented it is reviewed and changes are made if needed. This process is repeated until all business and technical requirements have been satisfied, at which point the “all clear” is given to move forward with implementing the design.

But what exactly constitutes a good design? How does one determine a good design from a bad one? In reality it could vary significantly based on a number of factors, however in my experience I have found a design can almost always be judged according to three fundamental criterion: Correctness, Cohesion / Coupling and Scalability. For the most part everything falls into one of these three categories. Below is a brief description of the specific design questions each category sets out to determine.

  • Correctness
    Does the design solve the problems described in the requirements and discussed by the team? This is Correctness in the form of satisfying business requirements. Are the patterns implemented in the design appropriate, or are additional patterns being used just for the sake of using the pattern? This is Correctness in the form of technical requirements. A good design is well focused and only strives to provide a solution which meets the requirements specified by the business owners, client etc; it does not attempt to be overly clever.
  • Cohesion / Coupling
    Has a highly cohesive, loosely coupled design been achieved? Have the classes, interfaces and APIs been logically organized? Does each provide a specific, well-defined set of functionality? Is composition used over inheritance where applicable? Has related functionality been properly abstracted? Does changing this break that, does adding that break this, etc.
  • Scalability
    Does the solution scale well? Is it flexible? A good design strives to facilitate change with confidence, and with as little risk as possible. A good design also achieves transparency at some level in the areas where it is most applicable.

    • The concepts outlined above are crucial to achieving a good design, however they are often overlooked or misunderstood to some degree. Throughout the years I have began to recognize some commonality in the design mistakes I find in Object Oriented Designs in general, and within Flex projects in particular. Many of which typically can be attributed to violations of basic MVC principles, but most commonly the design mistakes appear to be a negation of Separation of Concerns (SoC).

    There are close relationships between Correctness, Cohesion / Coupling and Scalability, each of which plays a very significant role in the resulting design as a whole.

    So lets start with Correctness, which is by far the single most important facet of design, for if the design does not provide a solution which satisfies the requirements specified then it has failed – all other aspects of the design are for the most part, details.

    It is important to understand that Correctness has a dependency on Flexibility. For example, as architects and developers our understanding of the problem domain is constantly evolving as we gain experience in the domain. Additionally, as requirements may change significantly as a product is being developed, our designs must be able to adapt to these changes as well. Although this poses some challenges it is wrong to suggest that requirements need to be locked down completely before the design phase begins, but rather requirements need only be clearly defined to the extent that the designer is aware of what is required at that point in time and how it fits into the “big picture”. A competent designer understand this well and makes careful considerations before committing to any design decisions. This is where the importance of Flexibility comes into play. In order for a design to be conceptually and technically correct it needs to be flexible enough to support change. This is why good design is so important – to easily facilitate change. As such the flexibility to allow change should be evident throughout the design. A good example might be where the middle-tier has not decided which service layer implementation will be used (e.g. XML:80, WSDL, REST etc.), or the Information Architects have not decided what the constraints of each user role will be. A good design should be flexible enough to allow for changes such as these as well as others with confidence and more importantly, little risk to other parts of the application; after all, you shouldn’t have to tear down the house just to renovate the bathroom – in addition to Correctness and Scalability, this is where Cohesion and Coupling come into play.

    High Cohesion is vital to achieving a good design as it ensures related functionality and responsibilities are logically grouped together, encapsulated and abstracted. We have all seen the dreaded, all encompassing class which assumes multiple responsibilities. Classes such as these have low cohesion and are a sign of future challenges if not addressed immediately. On a higher level, if high cohesion had not been achieved it is easy to notice as there will typically only be one class which comprises an entire API, however quite often low cohesion in classes may be a bit more subtle than one might expect and a code review will reveal areas where low cohesion has been implemented.

    For example, consider the following Logging facility which is intended to provide a very simple logging implementation:

    The above example is such a classic case of low cohesion. I see this kind of thing all the time. The problem here is that the Logger class has low cohesion because it is assuming the responsibility of creating and formatting a time stamp, this functionality is outside of the responsibilities of the Logging API. The creating and formatting of a time stamp is not a concern of the Logger, but rather would be the responsibility of a separate DateFormatting utility whose sole purpose is to provide an API for formatting Date objects. Removing the Date formatting functionality from the Logging API to a class which is responsible for formatting Date objects would facilitate code reuse across many APIs, reduce redundancy and testing as well as allow the Logger class to only define operations which are directly related to Logging. A good design must achieve high cohesion if it is to be successful.

    Coupling is essential in determining a good design. A good way to think of coupling is like this: Think back to when you were a kid playing with blocks, you could easily take any number of different blocks and rearrange them to build whatever you like – that’s loose coupling. Now compare that to a crossword puzzle or a jigsaw puzzle, the pieces only fit together in a very specific way – that’s tight coupling. A good design strives to achieve loosely coupled APIs in order to facilitate change as well as reuse. A classic, yet less commonly mentioned example tight coupling is in the packaging of APIs. Often, many times designers will achieve loosely coupled APIs however the APIs themselves are tightly coupled to the application namespace.

    Consider the of Logging API example from above, note that the API is defined under the package com.somedomain.someproject.logging. Even if the example were to be refactored to achieve high cohesion it would still be tightly coupled to the project specific namespace. This is a bad design as in the event another product should need to use the Logging API it would first need to be refactored to a common namespace. A better design would be to define the Logging API under the less specific namespace of com.somedomain.logging. This is important as the Logging facility itself should be generic in that it could be used across multiple projects. Something as simple as proper packaging of generic and specific components plays a key role in a good design. A better design for the above example would be as follows, this design achieves both high cohesion and loose coupling:

    As with all design, technical design is subjective. Architects and Engineers can spend an infinite amount of time debating the various points of design. In my experience it really comes down to organization and efficiency, that is, organization of responsibilities and concerns, and the efficiency of their implementation both individually and as a whole.

    It may sound cliche’ however before you begin a new design, or review an existing one, consider the following quote before doing so – it pretty much sums up what good design is:

    “Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.”
    - Antoine de Saint-Exupery

    November 7, 2008 Agile / Code Review / Design Patterns / Object Oriented Design / Software Engineering / Test Driven Development
    5 comments

    IoC and the Dependency Injection Pattern in Flex

    Within the vast catalog of Design Patterns available to software developers today, one of the most important to consider when designing an enterprise class RIA is the Dependency Injection Pattern.

    Dependency Injection, a term originally coined by Martin Fowler in his well known article Inversion of Control Containers and the Dependency Injection Pattern, is a more specific term for what is otherwise known as Inversion of Control or IoC.

    Fowler’s assessment of Inversion of Control containers concluded that the name itself – Inversion of Control – was too generic, thus as a result from his discussions with various IoC advocates they settled on the more specific term Dependency Injection, also known as DI for short. The terms Inversion of Control (IoC) and Dependency Injection (DI) are commonly used interchangeably to describe the same underlying design principle of separating configuration from implementation.

    There are three basic forms of Dependency Injection, which are generally referred to as type 1 IoC (Interface Injection), type 2 IoC (Setter Injection) and type 3 IoC (Constructor Injection). Before diving into the specifics of how to implement the various forms of DI, I will first discuss what Dependency Injection is on a conceptual level as well as what each specific form means. The examples outlined here are in ActionScript 3, however it is important to keep in mind that like most Design Patterns Dependency Injection applies to any language which supports an Object Oriented Model.

    At the most basic level Dependency Injection can be explained as a way of decoupling classes from their dependencies by injecting the dependencies into them rather than having the classes directly reference specific implementations. A class which directly references other classes is coupled to those classes – these are the dependencies. However a class which does not reference any other classes would probably not be very useful. At some point the dependencies need to be made. Dependency Injection is a solution to how those dependencies are made, and the manner by which they are provided.

    For example, consider the following class which illustrates a typical example of a class’s dependency on another class:

    public class ConfigurationManager
    {
        //defines the configuration to use
        private var config:XMLConfiguration;
       
        public function ConfigurationManager()
        {
             config = new XMLConfiguration();
        }

        public function getLogLevel() : String
        {
             return config.getConfig("logLevel");
        }
    }

    From looking at the code above the dependencies are pretty obvious; the ConfigurationManager class is dependent on the XMLConfiguration class. Now this type of dependency is quite typical so at this point you may be asking what is wrong with doing this?

    The first problem is that the config property is defined as a concrete implementation:

    private var config:XMLConfiguration

    This violates a fundamental OO principle:

    Program to interfaces, not implementations.

    More importantly and perhaps pertinent to the topic at hand is that it also isn’t very hard to imagine that at some point we may want to load a configuration from some other means, such as a properties file, a remote service and so on. In order to do so we would need to modify the class, and from this we can deduce that the class does not scale very well.

    So we could begin improving our current implementation by simply refactoring the ConfigurationManager class to define the config property as an abstraction, say IConfiguration:

    public interface IConfiguration
    {
        function getConfig(name:String) : *;
    }

    public class ConfigurationManager
    {
        //define the configuration as an abstraction
        private var config:IConfiguration;
       
        public function ConfigurationManager()
        {
             config = new XMLConfiguration();
        }

        public function getLogLevel() : Array
        {
             return config.getConfig("logLevel");
        }
    }

    As you can see this is certainly a step in the right direction, however the underlying problem still remains; we are still instantiating an instance of XMLConfiguration directly in the ConfigurationManager – and that is exactly what Dependency Injection is all about: providing a solution to the recurring problem of managing dependencies between classes, and how those dependencies are provided.

    When implementing the Dependency Injection Pattern in an application you do so by creating a context (configuration) which defines all dependencies in an application as well as an Assembler which is responsible for assembling the mappings and associations between objects and their dependencies. This is done by utilizing any combination of the three forms of DI; Interface Injection, Setter Injection and Constructor Injection. Below is a brief description of each form:

    Interface Injection
    Interface Injection is the process by which all dependencies are injected into an object via an interface. For example, the ConfigurationManager example above could implement an interface which defines the operations needed to inject the appropriate Configuration implementation.

    Setter Injection
    Setter injection as you may have guessed is the process of injecting dependencies via public setters; both explicit or implicit. Using Setter Injection the ConfigurationManager could provide public setters from which an Assembler could inject the appropriate Configuration implementation.

    Constructor Injection
    Again as you may have guessed Constructor Injection is the process of injecting dependencies via arguments in the class constructor. Using Constructor Injection the concrete Configuration could just as easily be injected.

    Both Constructor and Setter Injection are by far the preferred forms of Dependency Injection. Interface Injection has some major drawbacks as it somewhat leads to convoluted code since multiple additional interfaces need to be defined and implemented. The fact that “special” types need to be created and implemented in order to facilitate DI using Interface Injection greatly limits the potential for its use.

    There are numerous frameworks for various platforms which provide out of the box Dependency Injection implementations for all three forms of DI. All of these frameworks handle the wiring necessary for easily implementing Dependency Injection in an application, the most notable being the Spring Framework for Java/J2EE. There are also quite a few DI solutions for Flex and ActionScript applications as well. Optionally you could choose to roll your own however I would first suggest investigating some of the frameworks which are currently available as they more than likely provide what you need. The Prana Framework by Christophe Herreman is a good choice as it is one of the most prevalent DI solution available at the moment for Flex.

    Using the ConfgurationManager example from above I have provided a basic example application which demonstrates how to implement Dependency Injection utilizing the Prana framework. The example application uses constructor injection to provide a concrete Configuration to the ConfigurationManager, however I encourage you to experiment with the other mechanisms of injection as well. The example is intentionally kept very simple in that it is only intended to convey the basic concepts of DI and how to use it in Flex with Prana, from this you should have a good understanding of how to implement DI in a larger context.

    September 21, 2008 Agile / Design Patterns / Object Oriented Design / Software Engineering
    15 comments

    Class Annotations in Flex

    Class annotations, also known as metadata in Flex, are extremely valuable as they allow developers to provide additional information about classes, properties and methods which may not be appropriate to convey through implementation details such as Marker interfaces or some other means. An annotation can be viewed as a comment of sorts that provides a facility which can be utilized to convey the intent of a class, property or method, however unlike comments annotations are compiled into byte code with the class, thus allowing inspection at runtime via object introspection / reflection. Annotations do not directly affect code semantics themselves, however they can be inspected at runtime which in turn may affect the semantics of the running application.

    Annotations are also very useful for providing pre-compiler instructions for generating boilerplate code. Although custom annotations can not be used in this way directly in Flex, this usage can be found throughout the Flex Framework. A perfect example of how the Flex framework uses annotations to generate boiler plate code is the [Bindable] meta-data tag, which itself is an annotation as are all meta-data tags in Flex. When a class or property is defined as [Bindable] the pre-compiler in turn reads this attribute and generates the code which facilitates actual data binding; i.e. PropertyChangeEvent, IEventDispatcher etc.

    In order to use custom annotations in Flex you first need to instruct the compiler to keep Actionscript 3 metadata. This is achieved by using the keep-as3-metadata compiler argument. An example of setting two custom metadata attributes named “Foo” and “Bar” in the Flex IDE under project > compiler options is as follows.

    -keep-as3-metadata Foo, Bar

    Additionally annotations can be specified in a flex configuration file as follows:

    <keep-as3-metadata>
         <name>Foo</name>
         <name>Bar</name>
    </keep-as3-metadata>

    When you create custom metadata in Actionscript you do so by first declaring the name of the annotation followed by arbitrary properties specified as name/value pairs. For example, you are most likely familiar with the [Event] metadata tag in Flex. The name of the annotation is “Event” and the valid properties for the annotation are “name” and “type”, as can be seen below:

    [Event(name="eventName", type="package.eventType")]

    Likewise you create your own custom metadata following the same format. The example which follows defines a custom metadata attribute utilized for annotating a class with version information. The name of the annotation is “Version”, which contains three properties; major, minor and revision.

    package
    {
        [Version(major="1", minor="2", revision="123")]
        public class Model {
        }
    }

    Accessing custom annotations in Flex is accomplished via the flash.utils reflection APIs; describeType, getQualifiedClassName and getDefinitionByName.

    To help simplify the process of accessing custom annotations in Flex I have developed a simple API: MetadataUtils which is an all static class that provides utility operations from which class annotations can be located and inspected, and Metadata which provides a strongly typed implementation of a metadata entry.

    As you begin experimenting with your own custom annotations you will quickly find that there are numerous applications where they can be utilized, the most significant of which (IMHO) is to help facilitate IoC / DI solutions. It would be great if at some point Adobe would provide an APT implementation for mxmlc as part of a future release of Flex.

    September 13, 2008 Software Engineering
    2 comments

    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.

    May 27, 2008 Agile / Code Review / Design Patterns / Object Oriented Design / Software Engineering
    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 ) );
    }
    }

    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 );

    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;
     

    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
    ← Older Entries
    Newer Entries →