Taming Software Code Complexity and Technical Debt

bearAndHandlerThe project I’m currently on has a good deal of complexity.  Its built on a 10+ year old codebase that has passed through multiple development groups with varying levels of skill and pressures.  It can cause some problems around the team’s ability to deliver new functionality with speed and quality.
I’m currently in the midst of working with the team to get our team on the path of making the project less complex and more maintainable over time.  Here’s our approach:

Schedule Regular “Debt Payments”

If all new development goes into business driven features, and the complexity and cost to adding those features continues to rise, your project grinds to halt, hurting everyone.  Therefore its a good practice to bake in “debt payments” into your release planning, mean a certain percentage is reserved for improving your codebase.  This time is dedicated to things like driving down static analysis issues, refactoring brittle parts, building in automation, etc.

Keep a Debt Payment Backlog

Just like the business keeps and prioritizes a feature backlog, the development should keep and prioritize its debt backlog.  Just like team meets regularly to “groom” the business story backlog, the dev team should meet regularly and refine its technical backlog, so that it makes the most of its debt payments.  Care should be taken with this backlog and changes to the codebase should be made responsibly and socialized with business stakeholders.  They like to hear things like what is the risk involved with a change, and what tangible benefit will it give the product.

Socialize Architectural Direction and Patterns

Part of what got us into a bit of trouble in the codebase was that we inherited a some less than well-architected codebase.  It had a set of patterns that were less than ideal, and when developers went in to add new functionalities, they copied how things were done for the sake of consistency and ease, propagating the patterns.  Additionally different developers might have different ideas of how the same codebase should be developed.  This phenomenon of propagating anti-patterns and disjointed coding will continue unless the team gets on the same page.  What has helped our team is coming together regularly and talking about the various inherited parts of the system and coming up with a shared understanding of where we want that architecture to go.

Work Effectively with Legacy Code

The Boy Scout rule and Broken Windows theory are important concepts to build into your team culture.  If we fix a bug or add a new piece of functionality to an existing piece of code or develop something new, we want make sure that the code has no static analysis issues, has low complexity, and is covered by tests.  Michael Feather’s book on the subject is a great read for coming up with ways to effectively change existing code.

Understand and Manage Pressures

What I mean by this is that the development team needs to be in charge of what they deliver.  I’ve been on too many projects were quality was sacrificed for initial delivery speed, and this is what I have come to:  If we as developers are going to sign our name to something (which we do when we commit it to source control), it needs to be done with quality and care.  Its a professionalism issue and needs to be baked into a team’s culture.  This requires an ability to be honest with yourself and with your stakeholders, to be able to negotiate, and to be able to say no when you need to.

Getting on a path of creating clean and maintainable code can bring new purpose and life to a development team.  Its great to be on a team that is proud and in control of what they do.

A Simplified View of MV* Web Pattern Differences

I was asked the other day about the difference between common web architecture patterns and I stumbled around a bit explaining.  After thinking about it some I came to the conclusion that I’m much better sketching these types of things out, so I figured I capture this in a post.

Much of my understanding of the difference between web patterns comes from Martin Fowler’s post on the subject.  While its a fascinating read, it does take a while to read and digest.  Hopefully my rudimentary boxes and arrows can give a fairly straightforward depiction of the differences.  Solid arrows indicate dependency direction, and dashed arrows signify data binding.

MVC (Model View Controller)

Example Framework: Backbone/Marionette
Highlight: Databinding between view and model

MVP (Model View Presenter)

Example Framework: GWTP
Highlight: Presenter handles all presentation logic


MVVM (Model View ViewModel)

Example Framework: KnockoutJS/Durandal
Highlight: Databinding between View and ViewModel


So what’s Angular?  Angular describes itself as an MVW framework (Model View Whatever), as do others.  You can set it up to do any of the 3, but if you use its advertised features, especially the databinding between html and the scope object would suggest its more aligned with the MVVM school of thought.

Habit Wall – A Habit Forming App I’m Writing in React/Flux

After going to a cool JavaScript Meetup on React a couple of weeks ago, I decided to pick up a React app as my second webapp.  I got some inspiration from the Github contributions visualization to create an app that gives motivation and tracking for forming habits.  So for now I’m going to call this new app “Habit Wall”.  Here’s a wireframe of what I’m thinking…

HabitWallWireframeKind of like Strength-Tracker, I’m essentially building it for myself; to learn React, and to form some good habits;-)  I’ll put it on Github once its underway.

The app will work like this:  You define habits and pick how often you will perform them.  The app will essentially build a wall (most frequent habits at bottom), and fill in bricks when you perform tasks.   Your goal is to avoid holes in your wall.

Once I get the basic wall building behavior going, the next step would be to introduce achievements.  Some kind of award for keeping it up for extended periods.

As before, I’ll post updates as the app gets functional with thoughts on the technology.

Some Reflections on Coding MEAN

I’ve got strength-tracker basically functional, using the MEAN Stack (Mongo, Express, Angular, Node).  Still some stuff I want to do with it, but I figured I’d pause for some reflection on the technology and effort so far.

Directives are Widely Available

I came in thinking I would need to write directives for things like charting and modals, but I found that what I needed and more were available and free, and I could easily install them via bower.  I had seen a conference talk on Chartist and figured I’d try it out, and immediately found an angular project on github for it, which essentially required me to just create a json object for chart details and save it to scope.   Same thing when I needed a bootstrap modal.  I immediately found that there was a Bootstrap directive integration.  Angular has an active and thriving open source community around it.  If someone needs a directive that’s not around, it looks like they just create it and throw it on github.

Jasmine Rocks

I enjoy readable Unit tests, so Jasmine was right up my alley.  I used it along with Karma for unit testing.  Karma allowed for continuous running of my tests while I was developing, which was awesome.  The quirk about Karma was it didn’t give me an out of the box way to show the human readability of Jasmine, the thing that Jasmine excels at.  Never fear though, a quick google search brought me to karma-html-reporter, which gave me exactly what I needed (see below).   It describes the system behavior, which is not bad for unit tests:-)  Jasmine and angular have some mocking technology built in, and I did use it’s “spy” capability for a couple of assertions around calls being made, but I found that with javascript its really easy to create stub objects.  Also, I liked Angular’s pattern of dependency injection because it made for easy stubbing of services when testing controllers.

JavaScript on Client, Server, and Database meant no Data Transformations

Yeah that’s right.  The same json I kept in the UI as model is exactly what I was storing in the database.  I’m not used to this with as much with my years using java and sql on the server side, and it was pretty refreshing.  Traditionally I’ve had to go from a json format to java (with libraries like jackson), and then go from java to sql using things like Hibernate or DAO patterns, which while not rocket science, creates lines of boilerplate code that need to be maintained.  With MEAN I wrote remarkably little code to get what I needed, since I was just storing and retrieving a document from Mongo.  Each of my routes were just a handful of lines of code. Here’s a taste of the entirety of the server code to update the workout:

Strength Tracker Update Code

Angular Having data binding cooked in saved time

With Angular, you bind your widget directly to the model, so that your screen updates whenever you change your model, and vice versa.  I’ve built this into apps before, but having this natively cooked into the framework saved lots of time and code, and worked nicely for the strength tracker app.  There’s no save button implemented, so whenever the user updates data onscreen, the save happens in the background and the chart dynamically updates.  This was all done with very little code.

What’s Left?

My plan is to put the app out publicly where folks could use it or just play, but I wanted to add a couple of twists before getting it there. Of course getting an app working is usually the easy part – the bear is the last 20%.
  • Multi-User support and authentication
  • Add rep tracking as a choice in addition to 1RM (for things like situps and pull ups)
  • Add Integration tests using protractor
  • Nicer error handling
  • Add some additional styling
  • Do some testing/work so that it works nicely on mobile
  • Deploy it
Overall, I was impressed with how little code the MEAN stack required me to code to get my site going.  Also, I didn’t run into any perplexing issues (though the complexity level of what I was doing was relatively low).  Things were pretty straightforward, and I got things up and going with a fair amount of ease.  The solution hit two biggies for me: low amounts of boilerplate code, and nice testability.  I wouldn’t mind creating more stuff with it, though I have some other options I’m itching to try first.

StrengthTracker: My Public Foray into Writing a Useful Angular Application

In my previous post, I mentioned that I wanted to learn a variety of web frameworks for single page web applications, and the best way for me to do this was to write small applications that might be of use (to at least me:)

So here I go…

Essentially my plan for the first app is to develop what I’ve been doing during my workouts through Google Docs: Track weight and repetitions and track progress over time.  I’ll do this through calculating 1 rep max, or calculating straight repetitions for things like pull-ups and dips.  Its going to be visual so I can keep motivated, so I’ll incorporate charts to view progress.


My aim is to represent this in a single page web app, and make things like calculating one rep max and entering in workout data even easier.  Here’s a wireframe I drew up…

Strength Tracker UI

For 1RM (one rep max) calculations I’m grabbing some equations from the wikipedia site on this: http://en.wikipedia.org/wiki/One-repetition_maximum

I’ll go with the Epley Formula to start: 1RM = w(1+ r/30).  Later on it might be cool to add a settings pane where a user can pick a different formula


  • Client – Angular JS, Bootstrap
  • Charts – Chartist
  • Server – Node.js, Mongo, Mongoose
  • Build/Deploy – Grunt
  • Unit Test:  Jasmine/Karma

If you want to play along at home, or give me a pull request, I’m putting the code on Github: https://github.com/toddjordan/strength-tracker

When I’m done I’ll deploy it so somewhere like heroku and it can be a free service to anyone that want’s to try it out.

I’ll also try to post some lessons/thoughts from the technology stack as I go.  Below is what I have so far (very very early in dev):


Web Frameworks: A Redux

restartLast year, I embarked on trying to develop a simple web app on 6 different single page web frameworks.   In the last half of the year, I detoured to spend my waking hours on a super aggressive project at my job that showcased some ideas I had around the web space.  With the new year and things settling at work, I’m re-invigorated on exploring some different web technologies.  Having the advantage of some hindsight on the start of last year’s effort, I’ve decided to approach my tour of web frameworks slightly differently this time around.
Going From Useless to Useful
In my initial foray into the topic, I used a basic grid/form combination as my single page app to try to showcase a typical web application.  Since then I’ve thought of a couple of apps I’d like to write, so I decided to combine the 2 interests.  Each of the web frameworks will be put to use to create a simple app.  Here’s what I know that I want to do:
  • A Strength Training Tracker App
  • A Nonprofit youth outreach tracker
  • A Lawyer-Client Case work tracker (wife works for a law firm)
  • ? TBD for the rest, but I know I’ll have more project ideas by the time I need them
Keeping it Simple
For each one of these apps I want to get a minimal set of features going.  Each of these apps can easily suck up months and even years of my time depending on the bells and whistles, but that’s not my initial goal.
Completing the Stack
Last year, I just wanted to keep things on the client.  It was solely an exercise to get an idea about the frameworks.  This year in my chance to redo, I’d like to get more some server side coding under my belt, and expose myself to the backend technologies, such as node.js and mongodb.  Since I’m doing more fully functional apps, I’ll have the opportunity.
Being Non-Committal
Since this is an extracurricular activity for me, its going to fall behind my family and my paying job in my list of priorities (note I dropped the monthly progress goal I had last year).  This is going to happen when it happens, though I am motivated for the following reasons:
  • I enjoy it
  • It helps where I want to go in my career
  • I like finished projects
That said, I know I’m going to be more like that tortoise than the hare on this thing.  At the same time, there is possibly some work around executable spec driven UIs that I want to put out this year as well, which could slow this effort down.
Sharing it
I’d like all this stuff to be open source and on github.  I’ve created a github private account to start with, but as content gets built, I’ll transition my projects public.  The thought is that these projects will benefit me as the start a code portfolio, showing some of my work.   It will also open them up for others to join in case any of these get any traction.
I’d also like to continue my commitment to writing, so I’ll post here as I go on these things, keeping updates on what I’m currently working on.
Here we go…
So that’s my plan.  I don’t plan on any crazy commitments at work this year.  I believe a consistent drumbeat of quality code output, investment in some fellow developers, and in changing the way my team works will serve my company and my family life better. This balance should give me some time for some larger career goals.
In the end, I guess the major shift here is one of intent.  My goal is not to provide content to readers, its to share what I’m doing and finding interesting, and to grow as a developer, which is one of my loves.  If that happens to catch anyone’s interest, all the better ;-)