Category Archives: Jason Armstrong

Posts by Jason Armstrong

The Design Review – Only the Strong Survive

Posted on by
Reply

snaggle-toothed-dogLike a 10 year old heading to the dentist, the design review stage of a project is one of those areas that will drive a series of heebie-jeebies in even the most iron stomached software engineer or designer.  You’ve spent time with your users and business analysts.  You’ve diagramed all of the ins and outs of your solution.  Now you have to present your design to others and convince them why your design is the best approach to solving the problem within the constraints of your project.  Let the stomach aches begin!

When considering your upcoming design review, there are a few questions that you need to ask yourself.

  1. What is the target audience for this review?
  2. Has the audience spent the needed time reviewing your documentation?
  3. Are you prepared with answers to those reviewers that want to provide alternatives?

What is the target audience for this review?

Archery_TargetFor a successful design review you must understand your audience.  A strong designer will understand the technical level, responsibilities, and motivations in their design audience.  For example, if you are presenting your design to other senior technical leads within your immediate organization, you will want to structure your presentation to a level of technical review that is much deeper than if you are presenting to a group of architects.  Each type of audience will bring its own challenges.

Keep in mind that there is no design that at least one person can’t review and claim the opportunity for improvement.  Suggestions for change to your designs are occasionally motivated by technical philosophy instead of the merits of the design itself.  A well prepared presenter will use their understanding of the audience to work through these conditions.  As a rough example, sometimes a reviewer will believe that object oriented design is the answer to all solutions no matter the complexity of indirection and/or misdirection that object oriented design offers.  That person will likely challenge your designs on your use of data encapsulation, inheritances, and state if they are not all encompassing.  The more you are prepared to justify your design decisions for this review meeting in those low-level technical areas – they better you will be able to respond.  Just remember that a design review is not about finding a “different design” but to find the “best design” that meets the goals of your project.

Has the audience spent the needed time reviewing your documentation?

800px-Booster-LayoutThe single most time draining failure in a design review is if your audience has not reviewed your documentation before the meeting.  No one usually wants to sit in a two hour meeting listening to you read through your design document line-by-line.  Heck, I don’t even like having to read through my designs line-by-line.  To ensure your audience is prepared for your reviews, make the effort to give each participant the time to complete the review.  I also like to elicit a response from each participant before my design meetings where they are asked to confirm that they have read the design and are coming to the meeting to ask questions about the design itself.

At the beginning of the presentation, inform the participants again that the review meeting is an opportunity for them to ask questions about the design’s approach to solving the problem.   Good meeting management by the presenter is critical in preventing the meeting from turning into a document read-along.   If your project schedule and company culture allows, stopping the review for rescheduling if it becomes obvious that the review was not done by the majority of participants is sometimes a good peer-pressure trick to ensure the participants understand their role in the effort.

Are you prepared with answers to those reviewers that want to provide alternatives?

“Defence is our best attack” Jay Weatherill

The most effective tool a designer has in their arsenal is that of alternative solution investigation.  The designer must spend the time needed to explore the alternatives that may come out of a design review before the review occurs.  As quick on their feet as many designers believe that they are in answering a technical challenge with partially correct answers, I’ve seen situations where the reviewers that actually do know the correct answer to the technical challenge begin to doubt the designer’s credibility.  If you don’t know the answer to the feasibility of an alternative solution – just say so and take it off as a follow-up action.

Remember that the design review is not about you.  The review is about the proposed solution – not the person presenting it.  Assume your reviewers are looking for the best solution for the problem – not attacking your ability to design it.  In the end – if your design is well thought out and you’ve considered all of the possible fallacies of the approach – your design will only be improved by the combination of minds reviewing it but will usually enjoy more support from those that accepted the design.

720px-A_01_Audio_compact_disc_collection

I’ll provide a personal example to this topic.  I had worked on an application for two years of design, development, and maintenance.  The application had been reviewed over and over by at least 15 difference architects, senior developers, and designers over that period of time.  A new person joined the group and in about 45 minutes of reviewing the design suggested a hole in our solution that had been leaking memory for the entire two years.  We had been lucky enough to have loaded maintenance releases often enough to not have seen it – but sure as heck – it was there.  It never ceases to amaze me how just a single person can sometimes find something that the larger group never recognized.

In summary, embrace these design reviews.  Conducting a series of reviews taken in a positive manner and demonstrating solid understandings of risk analysis and thoughtfulness has propelled many developers into high-level roles and responsibilities.  Look at each design review as an opportunity for you to learn something new.  I assert that if you do – not only will you gain personally through your learning – but the designs you produce will be more solid and less prone to failure…and everyone like to support that kind of software.

Version Control of API and Other Documentation

Posted on by
Reply

In his post regarding “Version Control Your API Documentation with Github”, Kin Lane discusses an approach for using Github to version API documentation.  The post references using a single public repository to store and version the API documents with the APIs.  I agree with his thoughts and position.  However, I’d like to extend Kin’s thoughts into a practical problem seen if that solution is incorrectly understood and implemented at more of a root source control level.

The problem:  Assume that you have the repository structure below and you ask your novice developer to “check in” their API documents, database scripts, etc. related to this project (basically anything that is not really needed to “run” the code).

The concern: In this project structure (a Maven Archetype default), there is a strong risk that developers will place their API documentation into the resources folder.  However, since anything placed into this location is generally packaged with the deployable unit, suddenly your repositories (source control, Maven repositories, deployment folders, etc.) could see a swelling of storage needed to support the effort.

This storage concern is not a critical issue if your project is small and your documentation very minor.  However, small project efforts that allow bad habits have a tendency to create bad habits for a development organization as a whole on larger projects if they are not watched closely.  After all – who do you place on your projects other than a team of developers that have “already done it” but just on smaller efforts?

In a large project, you might suddenly see gigabytes of documents, diagrams, database schemas, etc. showing up in this resources folder.  Assuming that the projects might undergo hundreds of releases, branches, tags, and forks – this storage suddenly becomes an issue.

Imagine if your developers placed 2 gigabyte of “documentation stuff” into the project’s resource folder and requested that your build system should check out “a fresh” copy of the project once every hour so that it can execute a build and package after checkout (insane requirement – but I digress).  That is over 48 GB of data flowing back and forth between the source control system and your build servers each day.  Extending that assumption further- if you have more than one project at your company with that requirement – you might get a call from your LAN team.

The recommendation: Use strategies such as Kin mentions (along with the options below) to move your documents into a documentation repository and/or repository folder that is not automatically packaged with the release.

Option #1 (Recommended): Use a dedicated repository for documentation and hook them via technologies such as Github.

Option #2: Place the documents into a folder outside of the packaging process.  For example, place your documents into a folder at the same level of the root folder of the project.  You will still face the checkout issues – but at least you are not deploying your compiled package with a large set of documents.

Option #3: If you can afford it, invest into commercial toolsets.  Since I come from a SOA background there are things such as Websphere Service Registry and Repository, HP SOA Systinet, and Software AG.

Designing Long Term Solutions in an Iterative World

Posted on by
Reply

http://en.wikipedia.org/wiki/File:Development-iterative.gifIn this world of cost cutting and temporary resourcing, the importance of looking at the long term strategy when defining a solution’s design can get lost with the pressures of implementation deadlines.  How many times has a team been asked to shorten their design time in order to “get on” with the development effort and get something out to the market?  As a designer, how many times have you been told to worry about the fine grain details later – aka when we work on the low level designs for the developers?

Take an honest look at your project resources.  During requirements gathering we have; technical leads, business analysts, product owners, architects, project managers, and many others reviewing every single word in the requirements.  However, when the requirements are done, the team drops to a few technical leads and possibly some architects trying to push out a design with enough information to get the development effort started.   Who is inspecting every flow, component, and rule in the design?  Who is making sure that the design meets the basics of solid design fundamentals?

A respected VP and Director I know once told me that there are few things that are more important than a great design to make great solutions.  The analogy that was given is roughly repeated below:

“A good design is like a blueprint for a house.  Many designers can design a three bedroom house since the same blueprints usually work with a few tweaks on similar houses.  They know how to put in the plumbing, build a standard foundation, and where to put the doors.  However, I assert that the blueprint must be evaluated against the long term needs for the final solution.  If the blueprint is for a three bedroom single story house, they you should never expect that house to turn into a five story apartment just for the desire of making it one in the future.”

I’m a big fan of Agile and Iterative development methodologies.  These methodologies have moved development to greater flexibility and delivery capabilities in many ways.  However there is a catch…as there is usually a catch in all good things.  If there is not a blueprint for the final condition (or at least a review that ensures that the final condition can be supported) then no number of iterations or sprints will ever be enough to reach the final goal.

Let’s go back to the blueprint analogy and explore some of the detailed examples that came out from the analogy above.

Let’s say that the requirements from the new property owner describes a single story building that will support three people and will provide those people security from robbers and weather conditions.  Those owners know that at a later date they will be asking for something that will house 200 people, provide a gated security system, and contains a pool and tennis court.  However, since they really just want to get that single story house out there as soon as possible and start getting revenue from renters, they tell everyone that they will deal with those larger requirements “later.”

The designers look at the requirements and start building a blueprint for a house that  Designing Long Term Solutions in an Iterative World a Single Story House Viewhas a couple of bathrooms, a single-story-rated foundation, and standard deadbolt locks on the door.  Everyone likes the simple design, so the development teams start implementation and celebrate the completion of the single story house with great fanfare.  The owners have renters move in and praise everyone for the modest income they are seeing.

Later, the owners meet with the designers and ask them to add few more stories and 20 more apartments to the building so that they can get more tenants into the building and make some more money on an already winning income source.  After some tears and anger – the designers agree to give the owners what they want.  The designers decide that they will need to kick out the current tenants so that they can build a stronger foundation.  Then they realize they need to change the entire security model to include key card access and large gates to keep the strangers out and the tenants secure.  Finally, they are surprised to find that the city’s current residential sewer line will never support the new needs, so they design a new commercial-level sewer system for the property.

The construction crews that worked on the single story house are livid that they have to Designing Long Term Solutions in an Iterative World a Apartment Viewredo so much of their original work.  However, at least it is paying work!  They don’t have a lot of time to completely rebuild the foundation, so they decide that maybe they’ll just add some more concrete and hope that it will hold the weight.  They deliver an updated building and great fanfare is made of the new delivery.  Then the city inspectors are sent in.

The city inspectors find that the foundation is sinking under the weight of the new floors.  The sewer line could not be ran to the area because it was in a residential zone and commercial lines cannot be ran into the property unless they spend millions on rezoning and new city infrastructure.  Finally, after much finger pointing and lost money, the effort is shut down due to permit violations, zoning violations, and budget overruns.

So why spend so much time on the analogy above?  Because, this cycle is seen over and over again in the software design process that most teams work within.  How many times have we implemented software only to find that the initial authentication mechanisms were not adequate and we needed to implement complex single sign-on features using expensive third-party systems?  How many times have we seen software that was not thread safe and highly scalable because the development team thought they were building a 1 TPS solution vs. a 1,000 TPS solution?  For the operations folks – how many times has a team asked you to place a piece of software on your low transaction network only to find out that it was really supposed to be running across a highly redundant and highly scalable network?

How do we keep this from happening?

  1. Project owners need to insist that the teams (including themselves) do not get into a cycle of “we’ll figure out that complex feature later.”
  2. Designers need to understand the end state of their designs and implement solutions that allow for the migration from starting iterations into their final conditions without major foundation rework and redesign.
  3. Finance needs to ensure that they provide budget for efforts by giving the design team the resources and budget to ensure that they can understand and design for the end-point solution.
  4. Reward those teams that save time, rework, and funds by having a solid plan of how to get from state A to state G.
  5. Re-train those that feel that the measure of a good design is how many fancy window coverings, cool colors of walls and carpet, and number of awesome garden tubs that they can put into that single story house instead focusing on the long term goals.

The ideas above sound easy to do.  However, I am always amazed on the number of stories I hear at gatherings for development managers, designers, and technical leads across industries where they same comment is made over and over: “If I would have only known that they wanted it to me like that then I would have done everything differently.”   That said, over-engineering is also another challenge for good designs – but I will cover than in future posts.

In the end, give your design teams the tools and information that they need to create a design that meets the true needs of the solution and they will amaze you with the results.  Trust me – a few extra weeks in design can save thousands in development re-work.

Coding Standards: A Beginning

Posted on by
1

010712_1933_SOAGovernan1.pngWhile working on a proposal for a new open source incubator project, it came as no surprise that the topic of which coding standards we should use came to the top of my task list as code formatting arguments were raised.  In a flash of inspiration, I immediately provided the standard quick and concise answer:  “Lets use the Oracle Java Coding Conventions standard.”  Suddenly, the sun burned brighter and the birds took up in song as the brilliance of my efficient answer was delivered.  Later in the day, when I had more time to consider the ramifications of my earlier answer, I pondered that perhaps I had been too simplistic in the view of what the Coding Standards means to me, my project, and the information technology industry as a whole.

So…let’s be honest with ourselves here.  When push comes to shove, we do what we need to do to get the product out to the markets. How often do we tell ourselves, “who really cares if I used 5 or 10 spaces of indent” and “Why does anyone care that all of my variables contain a single letter?”  We know that true “format” issues don’t really matter to anyone other than only the most critical of code reviewers.  Also, we always tell ourselves that we will get back and fix all those little shortcuts we took (no comments, JavaDoc statements, commented out code, etc) just as soon as we have a little more time.  Besides, we also all know that badly “formatted” code runs in production just as well “formatted” code…right?

However, as I found some free time to myself  (aka the holiday period), I wondered if perhaps there were some things that are defined in high-quality Coding Standards that are perhaps a little more complicated that pure formatting.  An example of one of those items is found below.

STRUCTURE GUIDELINE – “Avoid nested method call at all costs unless it is completely guaranteed not to throw an NullPointerException.”

Example #1

this.theInstance.theMethod.getMap.get(“key”);

In the above example, there is a good possibility that this efficiently written single line of code will return a NullPointerException to the caller.  Code reviewers generally see samples of where this exception prone code is wrapped (usually later) as the example bellow shows.

Example #2

  1. try{
  2.      this.theInstance.theMethod.getMap.get(“key”);
  3. } catch (NullPointerException npe) {
  4.      log.error(npe.getMessage(), npe);
  5. }
  6. return npe;

When the NullPointerException message is inspected from the code above, the stack trace will tell you the line number that caused the exception (line 2), but cannot tell you if the Null object in this line was theInstance, theMethod, or getMap.  Suddenly, we begin to realize that perhaps high-quality Coding Standards can help us write more “reliable” code.

In summary, delve deeper into the coding standards available in the community and consider if your projects should use code formatting tools such as Checkstyle (my current preference) in their efforts.  It worked for me and hopefully it will work for you also.

Review of Enterprise Data Workflows with Cascading

Posted on by
Reply

Enterprise Data Workflows with CascadingEnterprise Data Workflows with Cascading by Paco Nathan (O’Reilly Media) is a great summarization of using the Cascading API.  Paco spends a sufficient amount of time providing a solid overview of Cascading along with an explanation of related extensions such as Pattern and Lingual. Test cases provided allow a novice user to quickly understand the basics of Cascading though some of the test cases followed along the same flows as the Cascading online documentation site.

Enterprise Data Workflows with Cascading is a great resource for beginning users that need to quickly come up to speed on using Cascading.  The book works the reader through evolutions of exercises such as setting up and loading files into Hadoop to using different types of joins along with finally reaching the point of integration points with the different languages and a larger case study based on the City of Palo Alto Open Data.

I’d recommend Enterprise Data Workflows with Cascading as a good entry point and base work to build upon as the reader gains more experience.

Review: Placing the Suspect Behind the Keyboard: Using Digital Forensics and Investigative Techniques to Identify Cybercrime Suspects

Posted on by
Reply

Placing the Suspect Behind the Keyboard

I wanted to take a look at a computer-based topic not normally in my programming domain and chose Placing the Suspect Behind the Keyboard: Using Digital Forensics and Investigative Techniques to Identify Cybercrime Suspects by Brett Shavers (O’Reilly Media).

As a former police officer, I found some of the discussions around generic evidence preservation to be slightly difficult to stay engaged with.  However, as a whole, Placing the Suspect Behind the Keyboard did not disappoint my desire to see what digital forensics was all about.  After reading this book, the reader should have a solid foundation to start delving into both the investigative and technical areas of a digital forensic investigator.

Placing the Suspect Behind the Keyboard takes the reader though a step-by-step process to ensure that digital investigations and interviews are carried out in a manner that will preserve the integrity of both your evidence and your suspects involvement.  Shavers reminds us throughout the book that it is not just about finding critical evidence on the digital device – but also ensuring that you can place the suspect “behind the keyboard” while those actions were occurring   With excellent references back to sources to keep you on track, Placing the Suspect Behind the Keyboard keeps the reader in line with well-established investigative procedures.  In addition, the Shavers also covers how to appropriately present your evidence to different types of audiences – something that is more challenging than most assume.

I highly recommend this book to a person just getting into digital forensics or that is looking for taking their technical knowledge to the next level.  While not a highly technical book, it is a great introduction into the digital forensics field.

Disclaimer: I received a free electronic copy of this book as part of the O’Reilly Blogger Program

Review: Metasploit – The Penetration Tester’s Guide

Posted on by
Reply

Metasploit: The Penetration Tester's GuideMetasploit: The Penetration Tester’s Guide by David Kennedy, Jim O’Gorman, Devon Kearns, and Mati Aharoni (O’Reilly Media) is very detailed and extremely valuable in demonstrating how penetration testing can be done using Metasploit along with having the great side-benefit of being able to learn about general methods and processes a pentester will go through during the testing cycle (PTES methodology).

The initial chapters deal with introducing the reader to the PTES methodology and Metasploit as a testing product.  As the chapters progress the authors pushes the reader deeper and deeper into the Metasploit product’s features along with how to use those features to complete the penetration test processes.  In the appendix, the authors have provided instructions on how to configure test environments that can support your exploits without sending the Feds to your front door.

Overall, this book is an good resource for those people that have good technical skills in Ruby and are comfortable in a Linux environment that want to understand penetration testing and the Metasploit product.

Disclaimer: I received a free electronic copy of this book as part of the O’Reilly Blogger Program

Review: Managing for People Who Hate Managing: Be a Success by Being Yourself

Posted on by
Reply

ManagingForPeopleWhoHateManagingAfter reading Managing for People Who Hate Managing: Be a Success by Being Yourself by Devora Zack, I was pleasantly surprised to find that the author had found a way to convince me to look differently at my “management” role.  In this relatively short book (133 e-book pages on my Nook) Zack guides the reader through several strategies to realize how you can take the “you” that earned that last promotion into the manager that you truly want to be – all without changing who you are.

In a writing style that is both informal and lighthearted, Zack works through many of the topics that we have all heard in management training sessions and management tombs – but never really connected with.  The conversation with the reader is in a style that makes complicated management strategies into manageable (pardon the pun) examples, stories, and thought provoking quotes.  After reading Managing for People Who Hate Managing: Be a Success by Being Yourself, I find myself refreshed and ready to work with the thinkers and feelers that are always all around us – while still remaining true to myself.

I highly recommend this book to new and experienced managers alike – and even a few employees wondering why their managers act the way that they do.  Sometimes, all a manager needs is a reminder of how we got here in the first place and Zack brings that to us in her book.

Review: Hadoop Operations by Eric Sammer

Posted on by
Reply

Hadoop Operations by Eric Sammer (O’Reilly Media) is a thoughtfully organized book that guides the operational and architectural reader into a viable Hadoop-centric solution.  In his book, Sammer spends a reasonable amount of time providing the reader with enough Hadoop background to be able to move onto the more complex considerations and actions needed to implement high quality Hadoop clusters in an operations environment.  Sammer provides some very specific information in his books that puts it into my “must have” collection for Hadoop.

First, instead of trying to cover what Hadoop can do in all flavors and colors, Sammer describes configurations that will meet the needs of a general operational implementation.  This allows the reader to focus on the key concepts of installing, configuring, and operating a Hadoop cluster instead of learning the many Hadoop features that most shops will never use.  Secondly, Sammer spends an appropriate amount of time discussing ways that an operational team can monitor and troubleshoot Hadoop clusters.  Very few authors cover the areas needed so that a solution can move from “proof of concept” into a “production-level” implementation.  Third, Sammer looks at products that work around Hadoop to either add features or allow for better maintainability/management of the system.  This gives the reader the ability to see how Hadoop fits into the larger operational model.  Finally, Sammer approaches the chapters in the book from the view of someone that has actually implemented Hadoop clusters by providing suggestion, tips, and tricks that allow the reader to bypass many of the more common challenges that Hadoop adopters can face.

I highly recommend Hadoop Operations by Eric Sammer for the operational and architectural readers that want to get a highly viable solution as soon as possible.

Disclaimer: I received a free electronic copy of this book as part of the O’Reilly Blogger Program

Review: Version Control with Git

Posted on by
Reply

A Review of Version Control With GITAlready having a background in advanced usage of ClearCase, CVS, and SVN, I picked up Version Control with Git by Jon Loeliger and Matthew McCullough (O’Reilly publisher) to understand how Git could help me solve some of the feature challenges I have been working through with other VCSs.  This book certainly was able to deliver to my expectations.

The authors work through the processes to setup and configure Git step-by-step.  In addition, they also spends a great deal of time delving into the more important topics required to work with Git as a power user.  The examples were useful and the diagrams where acceptable to convey the points needed.  There is no doubt that that the authors understand Git.  The time they take in explaining why to “do something” is important in moving the reader from a simple user of Git into becoming a power user.  The “Submodule Best Practices” chapter was helpful in solving some of my current challenges while the “Tips, Tricks, and Techniques” chapter gave me some quick wins.

While there are many ways to solve the same problem when using any VCS, I felt like the authors worked hard to provide an honest and open view of their approaches.  I highly recommend Version Control with Git to the reader that wants to understand more about a VCS like Git than simply a small number of quick commands via an IDE.  While this book is not a definitive reference guide in all things Git, it provides a solid foundation that allows the reader to head in the right path as they learn more about Git’s inner workings.

Disclaimer: I received a free electronic copy of this book as part of the O’Reilly Blogger Program