[ SAM Home ]
Sensible Assembly Methodology (SAM) Manifesto


Sensible Assembly Methodology FAQ


What is the Sensible Assembly Methodology?
The Sensible Assembly Methodology (SAM) is an approach to planning and developing software using the Adobe ColdFusion Application Server that maximizes code reuse and maintainability in an application. SAM is based primarily on principles taken from object theory ("object think") and Streamlined Object Modeling. SAM also borrows some concepts from Aspect Oriented Programming and encourages use of a few specific design patterns and practices taken from common J2EE development best practices that have proven themselves invaluable in the development of web applications. Much of SAM is also based on observations and lessons learned from many years of trial and error. The fundamental belief at the heart of Sensible Assembly Methodology is that an encouraged assembly paradigm and use of intelligent composable objects will always lead to well-written software.

What is an encouraged assembly paradigm?
An encouraged assembly paradigm, by definition, is any approach to construction in which the whole is constructed by assembling several smaller parts using a methodology that promotes decomposition of the whole. In software development terminology this requires the development of independent modules made up of encapsulated objects and any (encapsulated) modules required to provide an Application Program Interface (API) for accessing the object functionality and data. Software is built by integrating one or more of these independent modules.

What are 'composable objects'?
The idea behind composable objects lies in the concept that all objects are behavioral in nature. They are not only self-contained and self-aware but are also aware of other objects without which they could not exist. Taxonomies of smaller objects make the composition of larger objects within a computer software system and communication is channeled from the top of the domain taxonomy, down. Composition dictates ownership - lesser objects and specific objects belonging to larger, more complex objects that exist higher in the taxonomy. Objects at the top of a taxonomy are more aware and have more control of a larger number of other objects. Composable objects are behavioral - they interact with each other... almost as if they have a 'mind' of their own. Objects communicate directly with those other objects which they are either required to be aware of or that are lower in the taxonomy.

What is the goal of Sensible Assembly Methodology?
The goal of SAM is the development of succesful software. SAM is founded on the idea that software which is flexible and easy to maintain will be most successful most often. This is largely due to the fact that maintenance accounts for anywhere from 60 - 85% of the cost of owning and developing software. Thus, the primary objective of SAM is to achieve easy to maintain software. This is achieved by mastering the business domain to be modeled, practicing anthropomorphism when modeling the domain objects, and creating a parameterised and encapsulated API for using the domain objects. After modeling and planning, rapid implementation is achieved by repurposing any prewritten APIs and objects and by producing new APIs and objects for future use. The goals of the Sensible Assembly Methodology are achieved by following the Sensible Assembly Bylaws.

What is anthropomorphism and how does it apply to SAM?
Anthropomorphism is the technique of personifying objects. Objects are defined and developed by a developer that thinks of that object at all times in the first person. Learning to think like an object is the most difficult and most important skill that a software developer can develop.

If I use SAM, can I still use a framework?
SAM objects and their APIs do not depend on the existance of a framework, or much else for that matter. Their functionality and data are encapsulated and are unaware of their surroundings. As such, they should be able to be used in the context of any framework. That said, much caution is advised before considering developing an application using a framework, as this violates the SAM bylaw which states that objects do not depend on a central controller.

Can I use UML with SAM?
Yes, you can use UML with SAM, but it is not required nor is it encouraged. In general, UML is considered overkill for diagramming domains and applications, especially ColdFusion applications. It is generally acknowledged that the usefulness of a diagram lies in its ability to convey the desired meaning to others. It's generally believed, particularly by practitioners of object think (an hermeneutic school of thought) that diagrams really only hold the meaning originally intended by the author, to the author and not others. In other words, diagrams leave developers to interpret another developer's ideas without sufficient explanation. If you want to use UML to diagram, it is strongly suggested that you keep the diagrams as simple as possible. "Use Case" and "Class" type UML diagrams are the more useful (and simple) diagrams. You could even use simple UML class diagram to draw a semantic net diagram (see below).

How do I create a Semantic Net Diagram?
A semantic net diagram is a simple diagram who's sole purpose is to illustrate objects and the semantic relationships between these objects. A semantic net diagram begins by simply drawing a rectangle with the name of an object written inside. Another rectangle with the name of another object is also drawn. A line is drawn connecting the 2 and a short (usually 2 word) description of the relationship is written along that line. Typical relationships are: "is a", "has a" (or "owns a"), "can have", and "can be" though there are no hard and fast rules so long as the description is short and describes the relationship.

A semantic net diagram is a brainstorming tool used for object and relationship discovery - one useful approach is to go to a whiteboard and ask a domain expert to begin describing the domain. As you hear nouns, quickly put them on the whiteboard and try to diagram the relationships as you go. When they're done describing the domain, step back and look at the board; as you discuss the diagram begin deleting those rectangles (objects) that don't really need to exist. Add any that it turns out were missed. You may, especially in a large application, create many semantic net diagrams for a domain before you feel you've gotten it right.

Once a semantic net diagram is agreed upon, begin paper prototyping (see below).

How do I paper prototype?
Paper prototyping is a technique for object discovery. For each object in the domain, there is an index card. An index card begins with a statement at the top that declares who the object is ("I am a ..."). Below that, write a simple statement of purpose ("I exist in order to ..."). There are 2 sections below the statement of purpose - divide the remainder of the card with 2 headers: "I am aware of:" and "I am responsible for:". Below the first section list other objects and domain information that this object is aware of. You do not need to list individual properties here. Below the second section, list what functionality this object is responsible for contributing to the domain logic. You do not need to list individual method names here. Everything listed as "what I am aware of" and "what I am responsible for" should contribute in some way to the original statement of purpose, otherwise there is something wrong with what is listed or with the original statement of purpose.

In a team environment it is often useful to use giant sheets of paper - large sticky notes work very well, as you can stick them to the wall. Have a domain expert look at the sheets of paper and discuss what's missing, etc. Translate large sheets of paper to index cards when all objects have been identified. Creating a semantic net diagram (see above) will help to identify the cards that need to exist when paper prototyping.

After the paper prototype is complete, it is often useful to flip the cards over and list the actual method names and possibly also property names required for the implementation of the object.

Are there any other recommended techniques for object discovery besides paper prototyping and semantic net diagrams?
Yes, role-playing is another useful technique. The idea is, rather than diagramming the objects like you do with a semantic net diagram, each object is represented by an actual person (a developer or domain expert). Each person states "I am a...", "I am able to...", etc. and communicates with other objects (when acting out a story or use case) by passing a slip of paper between each other. It's a useful exercise for practicing anthropomorphism and for discovering objects and communication envelopes. Like paper prototyping and semantic net diagramming as a group, role playing is a great way to have fun as a team and to "wake up" the developers and get them thinking "outside the box".

How do I delegate tasks in a team environment when SAM being is used?
In a teaam environment, it's generally a good idea to assign one object, and any dependent ("owned") objects to each developer. That developer is responsible not only for coding and testing the objects but for creating the API for use in the presentation tier - the encapsulated UI modules, usually custom tag(s). The application itself consists of nothing more than tying these APIs together, so once all objects and APIs are built, development of the application itself takes very little effort or time.

Can I use design patterns if I use SAM and if so, which one(s)?
Yes, you certainly can. Technically, all code falls into one design pattern or another (or several) whether the developer is aware of it or not. SAM developers are mindful of the fact that design patterns can be a crutch, in that they do not encourage "object think" and in that developers often times have a tendency to get hung up on asking themselves questions such as "which pattern am I going to use here?" and "Is this a x pattern or a y pattern?". Design patterns generally do not play a part in the conscience planning of the business domain model - a "pure" object think approach is taken at that stage.

With the objective of keeping things simple, it is often times useful to implement a factory pattern so that all objects are retrieved/created from one place. This simplifies dealing with object packages, swapping one object for another, and impementing Singletons. SAM applications that will interface with other systems (other servers or rich clients like Flash) generally achieve this by implementing a facade pattern in order to expose the business domain model to the outside world. Under heavy load, a resource pool pattern implementation is often times the best solution (by keeping an available pool of objects in memory). In different situations, a design pattern implementation may be called for.

Whether or not a developer ever needs to look to design patterns to assist them in implementing their objects and APIs, SAM developers must recognize that if nothing else, design patterns are an excellent learning tool. Study them, try implementing them or better yet, try implementing generic implementations of them that can easily be dropped into SAM applications, but do not get caught in the trap of wasting valuable time memorizing and stressing over them.

If SAM encourages reusing the same files from application to application, doesn't that make it a framework?
No, SAM is not a framework. There are some core files that many SAM developers choose to use in the majority of their applications, but this is not required or encouraged by the methodology. SAM does encourage reuse of code both within applications and across applications, but the code that is reused is only that code which an application domain model dictates must be present. SAM applications consist of objects that are "intelligent" - these objects require no central control. Generally speaking, frameworks inject central control to an application architecture. Though SAM techniques can be implemented in the context of a framework, a SAM application has no real need for a framework either.

The SAM documentation frequently mentions "ownership" and also describes how "communication is channeled from the top of the domain taxonomy, down" - how is this different to central control, which SAM discourages?
Though central control is considered a poor practice and does not fit within the realm of object think, central coordination is a recurring theme in parts of the business domain in SAM applications. Objects that are not aware of each other, are often all either "owned" by an object higher in the taxonomy tree or an object in the business domain is aware of these objects even though they're not aware of each other. Though they do not need to be aware of one another, one object higher in the taxonomy may need to enumerate data from these other objects, or even coordinate their efforts sometimes, in order to meet its own objectives. In situations like this the "smaller" objects are not aware of each other but each is aware of the common "larger" object, which is solely aware of all of these "smaller" objects in the domain. The one "larger" object is performing a task that requires coordinating processes, namely communicating with many other objects. This is often the case when objects not only act on their own, but are also able to act as part of a larger whole.

Where can I download sample applications or reusable SAM modules/APIs?
At the moment, there is no central repository for sample applications or reusable SAM modules. CFPetmarket.com has a Sensible Assembly Methodology version of the petmarket application written by Simon Horwith, available at http://www.cfpetmarket.com/index.cfm?event=search.doViewProject&projectID=222C8635-1143-1024-A61ADA00462F8328. For several years, Simon has made APIs available on Macromedia DRK CDs and on his blog at http://www.horwith.com - these can be found easily by viewing blog posts in the "Downloads" category on his blog. Simon will be releasing more samples, including many of the objects and APIs that he frequently uses, in the near future. The SAM website will be updated to include a special "downloads" page as well.

I'm new to SAM - how do I know if I'm doing it right?
It's difficult to really judge "right" and "wrong" when talking about a methodology like SAM. One way to judge this is by the simple fact that you should be following the SAM Bylaws in your approach and implementation. When in doubt you can email Simon Horwith at simon@horwith.com with questions, advice, and clarification. Things to watch for in your code include having a presentation tier that is reusing UI modules (usually custom tags) rather than replicating code, a presentation tier that has "hidden" (encapsulated) interaction with business domain objects, and objects that are intelligent - self aware, encapsulated, and able to interact with the other objects that they need to interact without the intervention of a central controller.

How can I become better at implementing the Sensible Assembly Methodology?
Reading the suggested reading material (below) and studying the sample code (above) will help. Like most things in life, practice does make perfect and the best way to get better at developing SAM applications is to practice planning and developing applications using this approach. Simon Horwith frequently presents at user group meetings and conferences, often times about related topics, and Simon teaches a "Software Architecture for ColdFusion Developers" course for his company, About Web (http://training.aboutweb.com). In addition, you can email Simon at simon@horwith.com to ask him for suggestions, advice, and clarification.

Where can I learn more about SAM?
Other than studying the SAM documentation and downloading and studying the sample code and applications named above, keep visiting these SAM documentation pages as well as Simon Horwith's blog (http://www.horwith.com) for more. In addition to revisions to the current documentation as well as a SAM book that's in the works, plans are underway to add downloads, additional case studies, and illustrations of paper prototyping and semantic net diagrams to the SAM documentation.

Reading some of the suggested reading material (below) will also aid in learning "Object Think" and other skills necessary to develop with the Sensible Assembly Methodology.

What recommended reading is there for becoming a better architect/developer?
Simon Horwith is working on a book entirely about SAM and software architecture with ColdFusion - this book is not currently available. In addition, the following are recommended reading to learn object think, design patterns, and Object Oriented Programming: