Develpreneur: Become a Better Developer and Entrepreneur

We all make mistakes. Even our best intentions can lead to errors. Thus, we can make best practice mistakes. While this may seem like an impossible situation, you will soon see that it is common. Knowing the recommended approach does not mean we will follow it nor even that we should. Rules Are Meant To Be Broken The first thing to consider in avoiding best practice mistakes is whether your situation is applicable. There are extreme examples like knowing to wait thirty minutes after eating before swimming is no help in designing software. We need to apply these wise recommendations properly. The challenge comes when we are asked to determine whether a technology best practice should apply to our specific solution. A better technical example is the idea of data normalization. It can be argued that the highest normal form is best. The amount of storage space required is reduced, and caching may be more manageable. However, you will find that high levels of normalization lead to more table joins in your queries. In case you have limited join experience, the more joins in a query, the slower it will run. Modern database engines tend to be able to handle a few tables in a join, but once you get to high single-digit numbers of tables, it slows to a crawl. With that in mind, we can agree that any best practice should be seen as a recommendation instead of a hard and fast rule. Therefore, we can pick and choose how closely we follow a recommendation. We need to be clear on why we ignore one point while using another. General vs. Specific In the world of technology, we often see best practice mistakes related to generalities. It is important to remember that best practice recommendations are usually aimed at general software development. Your situation may not apply. Realtime and other processing-intensive applications can fall into this category. The flexibility we often desire from software has a cost. When your first goal is speed, flexibility is not worth that cost. Know the "Why" Ah, yes, we see this again. The "why" of a problem, a solution, and even an application is always essential for our success. That is why (no pun intended) we need to examine best practices with an eye towards whether each recommendation is one that applies in our situation. While it would be easy for us to follow them blindly, it would also be foolish.

Urban legends cover a broad range of topics and often have a feel of being correct, even when they are not. This phenomenon is not restricted to saying "Beetle Juice" three times. There are all sorts of urban legends that we run into, and they extend into the world of best practices. These examples feel like they are the right thing to do, but may even be the opposite. The Foolishness of Crowds Many of the problems with best practices devolving into urban legends territory seem to be rooted in groupthink. We do not always speak our minds, nor do we question enough. When we are worried about looking foolish, silence is often the path to take. However, this can cause all manner of issues when combined with communication challenges. Therefore, regular sanity checks of our processes are critical to keeping them on track. The Telephone Game Communication is easy to confuse. It speaks volumes that the old playground telephone game is also known as "Chinese whispers." Chinese may be easier to understand than the confusion that often comes out of this little past time. The essential point of the game is that every point of communication is also a potential point of failure. This weakness can even impact our best practices. The documentation and dissemination of those practices may not be perfect. That can lead to all manner of confusion over time. Thus, urban legends around our best practices may be the culmination of a series of minor miscommunications. Back To Basics The path to better best practices and avoiding urban legends is through regular reviews. We do not need to question everything all the time. However, we should question everything periodically. If for no other reason than to ensure we are all agreed on what our best practices are. Technology is changing our world every day. It is time to ensure our best practices keep pace with all of the latest advances.

Software developers and designers are often asked for a recommendation to approach a solution. The implication is that we know the right decision. We often join in on this assumption and will debate or argue that our way is the best option. While there may be a "best approach" to our problems, it is worth digging deeper into the costs associated with the right decision. Arguing For The Right Decision The first hurdle to overcome in assessing cost is debating the options. When there is a clear-cut approach that is the best one, then we can often decide and move on. On the other hand, there are more often going to be a few solutions that are similar, and a clear winner is not apparent. The time and effort spent debating and buttressing the options can become lengthy and even expensive. When the difference between the options is minimal, it may be best to choose one and move on. Hesitation alone can be costly. A Changing Environment We have looked at numerous situations where the best decision today is not as good tomorrow. We live in a world that is constantly changing. Likewise, new products and features turn up every day. That also is a reason to avoid splitting hairs in our desire to find the best solution. Those key indicators that make one solution the best can be unimportant by the time we implement. The more granular our focus on the arguments we make, the more likely our decision will be impacted by changes in the landscape. Progress Over Planning You can refer back to the Pareto Principle as an argument for making a decision sooner rather than later. The thought here is that the parts of the project that distinguish those similar solutions are going to live in that final 20 percent. In some cases, we may not even get that far into the solution in our first version. While we want to avoid decisions that may cause obstacles down the road. Sometimes multiple paths will lead to the same destination.

It is time to end another season. At this point, we need to revisit the idea of software architecture deliverables. In particular, we should spend some time thinking about how we communicate our architecture. Multiple Audiences for Software Architecture Deliverables First and foremost, there are a couple of levels of audiences that your deliverables will need to address. This situation is always one of the most challenging to handle correctly. Fortunately, we have other types of documents to learn from. We can look to similar deliverables like an RFP (or response to an RFP) for a structure and approach that makes sense. A Tiered Response Our prior discussions have covered this sort of "tiered response" or communication. We can craft a series of sections to communicate a growing level of detail. Therefore, we start with a summary, then move into core details, and finally supporting documentation. In this case, those sections cover executives, then implementors, and then architects or assessors of our work. The sections of the software architecture deliverables should flow nicely into the areas we want to address. The summary addresses significant decisions and the overall environment. We then move into the actual architecture. This section is often the most substantial part of our deliverables and critical for proper implementation. We can provide an addendum or an appendix to address the "backstory" of our architecture and details about our thought processes behind the design. Focus on The Varied Questions The critical facet of each section we have mentioned is how we address questions for the target audience. These issues should be treated as part of creating our deliverables. For example, managers and executives are going to need some points they can share with others about the general structure and platform. The implementation team is going to need detailed descriptions of how the provided architecture should be implemented. They will want to see how all the pieces go together and how to build each piece. Those that come after you will want to know what options were considered, why you chose what you chose, and paths that were willfully ignored.

It is time to wrap up the season of software architecture from scratch. We have covered a broad range of topics and now are able to look over them as a whole. There are common themes across the various areas that point us to software architecture best practices. Here are a few core concepts we should take from this season. Clarity is Key We have to communicate our results. These deliverables are essential in making our work valuable. Think about it, even the best architectural design is useless if it can not be implemented. When we fail to properly communicate our ideas, we reduce the likelihood of successful implementation. Therefore, pay attention to the details and note them in your deliverables. Likewise, provide some reasoning behind your decisions. A sort of historical record of your thought processes is invaluable to future architects. The world is constantly changing. Therefore, your architecture will be reviewed with an eye towards what needs to change. Your notes and "color commentary" can help speed the review by those down the road. Validate The Architecture A common newbie mistake is to build an architecture from an "ivory tower." Thus, the result is an academic masterpiece. However, it is not viable in the real world. We all know of concepts that look good on paper, but pale when we move into implementation. Every bit of the architecture that fails to be viable will reduce the faith in all of the work. It is best to avoid these confidence killers and instead validate your assumptions where possible. Yes, this may require a proof-of-concept or similar demo. On the other hand, your comfort in your assumptions will be worth the effort. A Place For Everything We sometimes get carried away with our architecture. This situation is particularly common when requirements change while we are working through architectural tasks. We may create a piece that is not needed or may forget to connect together some of the pieces. That means we need to do a final review of our architecture against the requirements before we wrap it up. Even a short amount of time can highlight blatant gaps we left in our design amongst the hectic schedule of changes. Sometimes the software architecture best practices amount to simply checking our work.

We have looked at a broad range of topics this season. However, it is time for us to tackle the middle tier architecture. Thus, we need to consider process steps (or flow) and look for commonality among the problems we solve. This area is not the most obvious to architect. However, it is an essential piece of the final solution. Middle Tier Architecture As We Go One of the challenges with the middle tier architecture is that it tends to get built over time. We design the front and back ends of the application. However, little time is spent on business rules and core logic. Data items and visual controls are more concrete for us to work with. The logic and problem-solving that makes up most of the middle tier tend to be nebulous. While that "squishy-ness" of the middle tier can be a challenge, I do not think we avoid that architecture. It just tends to be less noticeable. Of course, once you start to dig into the business logic, you will see all manner of pieces that can be used to build out an architecture. Your Personal Framework Generally speaking, the middle tier architecture is a framework for your solution. This area often contains the heart of the solution, and many of the critical problems solved for your users. When you think about it, the front end displays your solution; the back end stores it, and then the middle is where the work gets done. That alone should get you thinking that more time should be spent focused on the design and architecture of the middle layer. When you do things right, the resulting solution may be viable to spin off as a commercial product. Avoid Duplication The best outcome of middle-tier architecture is the avoidance of duplicate code. That is what typically happens when we allow this tier to grow organically. It is not until we see a lot of repeated code that we step back and refactor. That is a costly approach in time and effort, so it is worthwhile to plan and avoid this situation.

At some point in your project, architectural documentation becomes an essential piece of the deliverables. This material is often a set of diagrams and bullet points. However, there is more that we need to include. A good set of deliverables will consist of some defense of the decisions made. While this defense is good for CYA, it is more important when someone needs to consider whether a change is required. Basic Architectural Documentation The typical set of deliverables to achieve this goal covers what direction the implementation team should take. It is roughly a laundry list of decisions made and enough explanation to act on those. The result is a summary of the decisions made. That is in contrast to a synopsis of how the core decisions were made. Think of it as a set of marching orders with a "need-to-know" level of detail. There are situations where this makes sense. Some teams will only get bogged down when you provide them with high-level arguments. In those cases, the most direct and simplified architecture will be best for them to implement. Defending Your Decisions The goal of providing some history and defense of your decisions is not a means for those decisions to be second-guessed. Instead, you will help future architects avoid re-inventing the wheel. Think of it as similar to legal precedence in the court system. Rather than walk back through all of the possible sources and arguments, we can lean on the expertise of others to build on their work. A simple case is one where a vendor tool is selected. The vendors considered during the selection process and scoring rubric will help anyone that is asked to review that selection in a potentially new light. For example, a "new" vendor may become a hot topic in the industry. You can either score them against the criteria used or at update the scorecard for all vendors with a lot of the leg work done on those older vendors. You might even find that the "new" vendor was already considered. Allow For Change The critical point in all of this is to provide content that can be used when technology or requirements change. We know they will. Thus, the context around your decisions is crucial. This information will provide a quick view of your thought process. That can shorten the work required for future decisions.

A critical design decision in the object-oriented world is whether to choose cohesion or coupling. These two approaches are not mutually exclusive. However, it is rare to see a mix of the two. Therefore, this decision in the architecture will profoundly impact the rest of the project. Big or Small, Cohesion or Coupling It helps to set the stage for this discussion. The decision comes down to either building your system with small components or large (more full-featured) ones. The result can range from microservices up to a monolithic class that stands alone. A single object option is a cohesive approach, while coupling uses smaller classes that work together. Pros and Cons Each of these approaches has pros and cons. Thus, we need to evaluate which option is better for our specific situation. While most solutions can be implemented using either method, some will only be useful if done with one of the options. In general, considerations like performance, quality, and maintainability will be impacted by this choice. Fast or Flexible, Not Both There are several nuances involved in each of these options. Nevertheless, the decision will often boil down to building a system that is fast or that is flexible. This situation is not an uncommon trade-off that needs to be decided on during the architecture (and design) phase. A cohesive solution will often perform faster and tighter. On the other hand, a coupling approach is more flexible at the cost of overhead and speed. Either of these two options can be implemented poorly. Thus, selecting one or the other does not guarantee a specific outcome. However, it is easier to stay simple and fast using cohesion. Likewise, the coupling approach tends to be easy to adjust and extend.

Object names and namespaces are just the beginning of creating a class architecture. We need to consider globally available values, data hiding, abstraction, and how to group features. The old "is-a" and "has-a" questions are essential cogs in building out this piece. You will be looking for common pieces of data, methods, and how they should relate. A Goldie Locks Class Architecture It is incredibly easy to make your architecture too complex. There is a broad range of "best practices" that try to provide the best general solution. However, you are architecting a specific solution. Thus, keep that in mind as you create the object architecture. You should make every decision with supporting reasons for the related decisions. The last thing you want to do is be asked why you made a specific decision, and your answer is "because that is a best practice." You are not implementing a template; you are creating a solution, so do not be afraid to make it unique. Watch Out For Tools One of the complaints about coding tools is the extra stuff they include with a solution. While the tools can speed development and design, they also tend to need some supervision. Do not blindly trust these tools. There may be some real valuable functionality that they provide. Nevertheless, those results are useless when you do not understand what was done. An architect will need to share not only the end-result but also an explanation of why the decisions were made. This will be needed for implementation and future maintenance as well. Where To Begin Let's step back a step and look for where to start building out your classes. While the quick answer is always going to be in the requirements, there are better starting points. The user stories not only give us requirements, but they also give us context and a better view of the overall application. This higher-level view is needed for us to properly see how the pieces of the solution should work together.

Most modern business applications have some state or context. This model can be easy to implement in a stand-alone application. However, multi-user applications like web sites can be a challenge when you consider session management. While security is often a hot topic, tracking data correctly can be an issue to itself. We need to build our architecture to handle the ways we pass around such data. Session Management Is More Than Global Values One of the "rookie mistakes" of session management is the use of it as a sort of global bucket. It is not uncommon to see all manner of objects and values shoved into the session. While this approach makes it easier to pass values, it is not secure and wastes resources. Therefore, it is important to think through what values should be stored. As with manner, other design decisions, when in doubt, leave it out (of the session). There should be a strong reason for each item you store at the user or application level. Now Vs. Later Comparison While we just said it makes sense to keep the session small, there is also caching to take into account. There are valid reasons to store values in the session rather than make multiple calls to retrieve them. Thus, this is not an area of architecture that is always cut and dry. There are application-specific requirements that will come into play. Keep in mind the trade-off of memory to cache data and network traffic to load it. Design, Not Implementation We can always kick decisions like this down the road. The implementation team can make choices related to caching data and session management. However, that can lead to ad-hoc storage and other challenging to maintain situations. It is worth the time and effort to architect your session situation. Future developers and maintainers will thank you,