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:

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:

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.

Back in September 2008 I published a post on Class Annotations in Flex, through which I provided an API allowing for a unified approach for working with AS3 metadata. Just recently I intended to use the Metadata API in a Flex 4 project when I noticed it no longer seemed to work as expected. After a bit of debugging, I realized the bug appeared to be related to changes in the result returned from describeType; specifically, the addition of the “__go_to_definition_help” metadata. Considering the Metadata API leverages describeType in order to introspect metadata definitions, this made sense.

I made some simple modifications to the API to work with the new metadata returned from describeType and this resolved the issue. While I was in the process I also refactored operations to return Vectors as opposed to ArrayCollections, as was the case in the original design; effectively optimizing the API for Flex 4 (as well as Flex SDK 3.4).

You can download the source/tests/swc/docs dist here; all of which will be available soon via SVN and a public Maven repository, more on that once it’s ready.

For the past 4 years or so I have provided quite a few AS3 APIs as Open Source to the Flex Community, via my blog. These APIs can typically be found at the Open Source AS3 APIs page however, the page is basically just a URI to a series of arbitrarily added AS3 source classes. It was originally intended to simply serve as a convenient location to access the source, and it had always been my intention to eventually break out all of these APIs into seperate SVN projects.

So with that being said I am finally in the process of making the structural changes I had originally envisioned. Moving forward I will begin the process of creating seperate SVN projects for these Open Source APIs; with the primary goal being to provide practical APIs that only require minimal (if any) dependencies on additional libraries, complete test coverage via Flex Unit 4 and Mavenized builds.

The first project to move over to the new project structure will be the AS3 collections project as the classes in this package, specifically HashMap, have proven to provide the most value according to community feedback.

So stayed tuned!

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.