On Code Reviews

Recently, a colleague reached out looking for advise on documentation for code reviews. It was a simple question, like so many others that arrive in my inbox phrased as a “quick question” yet don’t seem to have a “quick answer”. It struck me as odd that we didn’t have a template for this sort of thing. Why would we need this and under what circumstances would a template help?

After some careful contemplation, I landed on two scenarios for code review. One definitely needs a template, the other does not.

Detailed Code Analysis

If you’ve been tasked with writing up a detailed analysis of a code-base, I can see benefit for a structured document template. Strangely, I don’t have a template but I’ve done this task many different times. The interesting part of this task is that the need for the document is often to support a business case for change or to provide evidence to squash or validate business concerns. Understanding the driving need for the document will shape how you approach the task. For example, you may be asked to review the code to identify performance improvements. Or perhaps the business has lost confidence in their team’s ability to estimate and they want an outside party to validate that the code follows sound development practices (and isn’t a hot mess).

In general, a detailed analysis is usually painted in broad-strokes with high-level findings. Eg, classes with too many dependencies, insufficient error handling, lack of unit tests, insecure coding practices. As some of these can be perceived as the opinion of the author it’s imperative that you have hard evidence to support your findings. This is where tools like SonarCube shine as they can highlight design and security flaws, potential defects and even suggest how many hours of technical debt a solution has. Some tools like NDepend or JArchitect allow you to write SQL-like queries to find areas that need the most attention. For example, a query to “find highly used methods that have high cyclomatic complexity and low test coverage” can identify high yield pain points.

If I was to have a template for this sort of analysis, it would have:

• An executive summary that provides an overview of the analysis and how it was achieved
• A list of the top 3-5 key concerns where each concern has a short concise paragraph with a focus on the business impact
• A breakdown of findings in key areas:
• Security
• Operational Support and Diagnostics
• Performance
• Maintainability Concerns (code-quality, consistency, test automation and continuous delivery).

Peer Code Review

If we’re talking about code-review for a pull-request, my approach is very different. A template might be useful here, but it’s likely less needed.

First, a number of linting tools such as FXCop, JSLint, etc can be included in the build pipeline so warnings and potential issues with the code are identified during the CI build and can be measured over time. Members of the team that are aware of these rules will call them out where appropriate in a code-reviews or they’ll set targets on reducing these warnings over time.

Secondly, it’s best to let the team establish stylistic rules and formatting rather than trying to enforce a standard from above. The reasoning for this should be obvious: code style can be a religious war where there is no right answer. If you set a standard from above, you’ll spend your dying breath policing a codebase where developers don’t agree with you. In the end, consistency throughout the codebase should trump personal preference, so if the team can decide like adults which rules they feel are important then they’re less likely to act like children when reviewing each other’s work.

With linting and stylistic concerns out of the way, what should remain is a process that requires all changes to be reviewed by one or more peers, and they should be reading the code to understand what it does or alternative ways that the author hadn’t considered. I’ve always seen code-review as a discussion, rather than policing, which is always more enjoyable.

The first User Story for your next Project

For your next project, consider adding this story to the very first sprint:

As an administrator I want to install the program with an installer so that I can have everything in place without manual setup.

Acceptance criteria:

• Application should run and show an empty screen
• Application should produce a log file that shows debug diagnostic information that can be used to trace through application runtime (timestamp, thread, logging level, component, message). Any fatal errors during start-up should be recorded with helpful diagnostic details.
• Any prerequisites for the installer must be known in advance or bundled with the installer
• The installer should have a minimal user-interface and optionally support running unattended
• The installer should put a shortcut on the desktop and start menu

Sure, this is great, but why should this be the first story in my project?

The short answer is this is the best time to do this. An installer created at the beginning of the project is often very simple as it will likely only be a handful of files. If you’ve ever written an installer, you’ll know that it can be a lot of work establishing all your dependencies and user-interface. If you wait until the end of the project when time is often a critical resource, you’ll fall into the trap of dropping this feature.

The beginning of your project is also a really good time to start thinking about deployment. By creating an installer you’ll have a packaging mechanism for your testers and business stakeholders and every time they install your application they will be regression testing the deployment. Bugs will be found, and the installer will get better and more robust as the project advances. From a development perspective you might think of this as re-work. Try to break out of that mindset and think of it more like spreading the work over the project in small increments.

As a final note, you may notice that some of the requirements refer to non-functional requirements like diagnostic logging. I’ve found this is a great way to set scope for the developers when referring to the initial “empty screen” and has an added benefit that lets testers know the location of the log files. Also, it allows you to associate defects for weird start-up errors and crashes to a User Story.

Happy coding.

Kanban, TFS style.

I’ve been building up a system of tracking tasks using User Stores in TFS for almost two years and I’ve been blogging as I go. Over time, I’ve written several short emails to colleagues pointing them to the Kanban tag of my blog, but that tag list is a bit heavy. Here’s a quick recap of helpful posts that can get you up and running.

Getting Started

If you’re a developer, team lead or architect – you should start here.

1. My first month with Kanban – a quick walkthrough that discusses my initial observations with Kanban. Old school, using a whiteboard and sticky-notes.
2. Using Kanban with TFS – a high level overview of the process I’ve adopted for tracking Tasks in TFS using Kanban columns. Provides an overview of customizing work-items.
3. Configuring SEP Teamworks – a walk through how to set up SEP Teamworks, my favorite free tool for viewing TFS items in a sticky-note fashion.
4. Using User Stories with SEP Teamworks – Revisiting my workflow slightly to adapt to using User Stories instead of just individual task tracking.
5. Setting up Areas and Iterations – Shows you how to organize your stories into TFS Areas & Iterations, and then using SEP Teamworks features to simpli

Reporting and Querying

If you’re a project manager and you want to set up SEP TeamWorks. Please read:

1. Working with TFS WorkItems in Excel – includes a walk through on how to set up your machine, and export queries to Excel.
2. Configuring SEP Teamworks – a walk through how to set up SEP Teamworks, my favorite free tool for viewing TFS items in a sticky-note fashion.

Advanced Customizations

1. What’s new in SEP Teamworks 1.0.31 – highlights some of the new improvements in the latest release: Card Editor to customize views, creating linked work items.
2. Marking Kanban items as Blocked – demonstrates how to customize your work items to take advantage of marking items as blocked.

Fix your code with an “On Notice” board

The above comes with thanks to the On Notice Generator, and my board re-iterates a lot of the guidance found on Miško Hevery’s blog. These are code patterns and anti-patterns that I’ve encountered on many projects and have strong feelings against. Some of these are actually on my Dead to Me board, but there wasn’t a online generator.

I think it’s a good habit to start on On Notice board for your project – a list of offending code that should be cleaned-up at some point. Often, these unsightly offenders are large and tightly woven into the fabric of our code so they’re not something that can be fixed in a single refactoring. But by placing these offences on a visible On Notice board, they become goals that can fuel future refactorings.

You might not be able to fix a problem in a single session, but you can add a 2 hour research task to your backlog to understand why it exists. The output of such task might be further research tasks or changes you could introduce to shrink their influence and eventually remove all together. Sometimes I bundle a bunch of these fixing tasks into a refactoring user story, or slip a few into a new feature if they’re related. Over time, the board clears up.

Don’t forget, while you’re making these changes, write a few tests while you’re at it.

Oh, regarding Gluten-free cookies… they look like cookies, but they are most definitely not.

Using Areas & Iterations in SEP TeamWorks

TFS supports a concept that allows you to organize your work items into different functional areas and chronological iterations, called Areas & Iterations. This post shows you how you can use these features to groom your Work Items using SEP TeamWorks.

Areas & Iterations in TFS

Areas & Iterations can be accessed from the Team Explorer.

Visual Studio 2012

Selecting this item opens a single dialog that allows you to configure both Areas & Iterations. Note that you’ll need to be an administrator for your Team Project in order to make changes.

Areas

The following shows an example of functional areas for a product.

Iterations

The following shows an example of Iterations.

Both Areas & Iterations can be nested so you can structure them any way you want. The system is also flexible if you delete an item you’ll be prompted to select a new value work items that would be impact.

Querying Work Items based on Path

When you query Work Items, you can find all items within the hierarchy.

Using Swim Lanes with SEP TeamWorks

SEP TeamWorks doesn’t have any built in mechanism to filter your TFS queries, but it has a fantastic feature that let’s you group content using swim lines.

Swim Lanes can be turned on any query (except hierarchical queries), simply right-click (long-press on your touch device) to open the context-menu and choose Edit Swim Lanes. You can also access the swim lanes from the Options button in the UI.

You can create Swim Lanes for most fields, assuming that the Work Items in the Query support the fields you’re grouping by:

Here’s the same query with a swim lane enabled for Iteration Path.

Where swim lanes really shine is you can use them to edit your work items without opening them simply by dragging them into another lane.  Here’s some great examples:

• Bug Triage: write a query that pulls back all new bugs then use swim lanes for Severity, Priority, Found In or Triage status. 
• Product Planning: write a query for all User Stories then use swim lanes for Area path, Iteration path, Risk, Story Points
• Grooming the backlog: write a query for all Tasks then use swim lanes for Activity, Area, Assigned To, Remaining Effort

As you can see, with a little bit of planning and some creativity you can customize the tool to fit your needs. In the upcoming posts, I’ll look at common queries and exporting information out of TFS into other formats.

Until then, Happy Coding.

Using User Stories with SEP TeamWorks

When I first started with Kanban over a year ago, the post-it notes on my whiteboard represented Tasks and Bugs, which for the most part worked great. The two main challenges raised by the team, were:

• Developers had a hard time visualizing related tasks, which made it difficult to organize and plan effort. We also had the risk of being unable to deploy because some related tasks were unfinished.
• Project Managers had a hard time reporting progress on high-level features. Although they had access to the Kanban board, organizing a status report from low-level tasks and bugs wasn’t sufficient.

Kanban is intended to be an adaptive process, meaning that it’s not a full-featured methodology and you pretty much have to add your own rules and concepts to it so that you can adapt it to your needs. Other methodologies, like Scrum, have solved my problem by using User Stories to represent high-level features that you can group related tasks under. Developers could see related tasks; project managers could report progress on Stories – win / win. The only remaining challenge was how to represent User Stories on a whiteboard? (How do you associate post-it notes with a Story? Do Stories move on the board like Tasks do? If a few of the tasks for a Story are “ready for test” does the status of the Story change?)

I struggled with this challenge until I switched over to a digital Kanban board which afforded us the ability to produce different queries over the same data. We’re using TFS 2010 as a repository and SEP TeamWorks as a front-end to visualize task effort.

Querying and Displaying User Stories

The Agile Process Template used by TFS 2010 includes a User Story work item type which you can link tasks to in a Parent-Child relationship. You can write a simple query to obtain all parent-children tasks. 

Note that the TFS query that I’m using is a Work Items with Direct Links query, which allows me to pull back Children tasks as well as Related bugs. I also don’t nest my User Stories – this technically works within TeamWorks, but it seems a little odd and needs some further investigation.

SEP TeamWorks supports hierarchical tasks out of the box. Stories and their children are represented as swim lanes, with the first column representing the Story.  Note that because Stories are broken into swim lanes, you can’t use TeamWork’s swim lane feature to further refine the query. If this is something you want, you’ll have to set up different TFS queries.

Adjusting Kanban Workflows

While the workflow that I’m using for Tasks and Bugs would work for User Stories, it seems a little heavy to duplicate the process for Stories. I simplified the flow to make it easier to manage and for reporting status.

The flow for my Tasks and Bugs, which I’ve outlined in my previous posts, is:

• Proposed
• Active
• Selected
• In Development
• Ready for Test
• Testing
• Acceptance
• Closed.

For my User Stories, I’ve simplified it to:

• Proposed: the story does not have all the details, yet.
• Active: the story is well defined and is actionable.
• In Development: the story is being developed or validated by developers
• Testing: development has completed and the testers are running their test cases
• Acceptance: test cases are complete and its ready for client review
• Closed: the feature has been accepted / shipped / etc.

Note that SEP TeamWorks uses the Status column from all Work Items into its UI so I’ve repurposed my existing status definitions to simplify things.

Daily Operations

As mentioned previously, having our Kanban board as software solution allows us to query and represent the data in different ways. I use a combination of three different queries for my daily operations:

• Product Planning: I query only User Stories which allows me to see the high-level status of the project at a glance. I heavily use Areas & Iterations (I’ll blog about this next) to help organize and plan the project.
• Iteration Backlog: I use a hierarchical query as shown above to represent the current iteration.  This query allows me to see the detailed status of the Story
• All Work Items: This query returns all Tasks and Bugs and it resembles the Kanban board I’ve fallen in love with. This query allows me to see bottlenecks, developer allocations, etc.

Conclusion

Having User Stories has made a big difference for how we track and organize our effort, but it’s not without its challenges. There’s a special knack to writing stories and it takes some practices to get used to the format, which I’ll have to blog about later. For now, I hope that this post shows you how easily it is to introduce Stories into your Kanban flow.

Until next time, happy coding.

My first month with Kanban

Just before the Christmas break, I took over an existing project that was approaching a major milestone. It's a great project: a small team, working with a high profile client to build a modular MS Surface application that ships a new release every few months.

You would think that taking over a project in the late stages of development would be a bad thing, however it's been fairly positive experience. Although the project suffered in the beginning as our bandwidth was reduced while I was ramping up, the opportunity to introduce a fresh set of eyes with a different perspective has allowed the team to innovate and challenge their assumptions (I’d like to think it’s been for the better).

One initiative that I felt that the project needed was some form of Agile methodology.  Although we had a set of high level stories that we knew had to be implemented, there was no breakdown of the tasks or ability to gauge progress. Despite this obvious need, I knew Agile was going to be a tough sell: the project has a highly dynamic, fast pace environment where requirements and tasks change daily. Adopting a full-on Agile agile process seemed too formal. I might be able to establish a backlog, maybe some task estimates -- but trying to establish planned iterations with client involvement? Not a chance. Besides, I'd likely wind up losing a good chunk of my day managing the status of tasks and justifying burn down charts to management.

This was a great opportunity to try something new. I had heard about Kanban before, but didn't understand it enough to put it into practice. I found this great eBook (free) that explains Kanban by outlining the differences between Scrum and Kanban. I highly, highly recommend. Download it now.

The following is an account of how we put Kanban in place…

Kanban in a nutshell

Kanban is a very lean process methodology that is based on a subset of agile/scrum. Whereas Scrum comes with rules about how to work with iterations and stories, Kanban comes with nearly no rules at all. In fact, you often have to add your own rules to Kanban in order to align it to your project/organization.

At a high level, Kanban is all about visualizing the work as a workflow on a "Kanban board". User stories are often depicted using sticky-notes, and they travel through the workflow on the board. Although you could easily do the same thing with Scrum, the key difference is that a scrum board would be reset at the end of the iteration. Kanban doesn't have the concept of iterations, so the board is the project.

Visualizing our Workflow

Before we could dive into realizing our project in a sticky-note form, we collaborated a bit to determine what our development workflow would look like. Although our process utilizes graphic designers from time to time, we decided to limit the scope of our Kanban board to the development pipeline only.

As mentioned previously, our process for this project isn’t very well defined. The majority of our work is based on a SharePoint list that our client has access to, and we log defects and work items there. Each day, we pull things from the list and work on them until we reach a deadline for a release or have completed all tasks to the best of our ability. It’s not the best system, but it’s just enough to work. The team decided that the best place to start with our Kanban workflow was in the middle where we were most involved, so we’d have two columns to represent the development tasks:

• In progress: Items that the team is actively working on.
• Done: Items that the team has completed development and are ready for testing.

Of course, our process doesn’t end once development is complete. From here, we package up a release and deploy it to a local Surface device in the office where other members of the team can see our progress. The team decided that we should do this more frequently and with some consistency, so we added another column for this:

• Surface: Items that have been deployed to a local surface machine for verification. If we identify problems with any of these features, they go back to the beginning of our process.

Eventually, once all the stories and tasks have been completed, we bundle up our changes and deploy it to our client’s surface machine for their testing and feedback. The process repeats until the client accepts the current package and it is released to their Surface machines. We represent these steps with another two columns:

• Client: Items that have been deployed to the clients’ location. It’s rare that stories are rejected by the client, but there’s often a lot of feedback that gets added to the beginning of our pipeline.
• Live: Items that have shipped.

At this point in the exercise, we’ve captured how things are currently executed on this project. The astute will recognize that the beginning of the workflow is lacking definition – I’ve not outlined how we account for tasks that aren’t actively being worked on, or how effort is prioritized. I’ve deliberately left this out, partly because I feel the pipeline has two distinct parts (an incoming and outgoing flow) but mainly because it’s a good way to explain one of Kanban’s core features: work-in-progress limits.

Keeping the team focused by establishing Limits

Clearly, our workflow will have a column that represents a backlog for our remaining effort. Although I could add it to the beginning of our workflow, which would make our Kanban board look a lot like a standard Scrum burn-down chart, there isn’t anything that would prevent us from falling into our old habits. In a highly dynamic project like this one, there’s a constant barrage of client requests and other noise that is beset with a sense of immediate urgency – most tasks get assigned to a developer and go straight to an “In Progress” state as they arrive. Essentially, if there aren’t any rules about when things are allowed to be considered In Progress, then there aren’t any reasonable expectations for the schedule of that work. This creates a real problem with managing client expectations and keeping track of what tasks people are actually working on. While there’s something to be said about multi-tasking, a team without focus gets nothing done.

To resolve this issue, we take advantage of one of Kanban’s unique features. At the top of our In Progress column, we add a number that represents the maximum limit for items in that column. This is known as a work-in-progress (WIP) limit. Since developers only have one head and two hands, we assume that developers should only work on one task at a time. This is easy math for a team of two developers.

By limiting our In Progress items to 2 we put a spotlight on the items that the team is actively working on, but this also creates a visibility problem about which items will be worked on next. To help visualize the priority of items, we add another column:

• Accepted: These are the work items that the developers will work on after they complete the In Progress tasks. We refer to them being as “Accepted” because the development team has reviewed the tasks and has committed to delivering these features.

To prevent the Accepted column from getting bloated, we give it a WIP limit of 4. This ensures that the developers have just enough prioritized items in their queue to keep them busy for the day. We could go higher, but 4 is a very manageable number.

Adding Rules and Events

As mentioned previously, Kanban doesn’t have many rules and you need to add your own to suit your needs. Here are a few rules that we’ve established:

• Our project manager is not able to manage any of the columns except the Accepted and Backlog columns. This means he plays a key role in helping to direct the work towards client expectations. Indirectly this also means that he’s not able to interfere with work in progress.
• When the Done column has enough items (we’re still trying to figure out a proper WIP for Done) we halt development and deploy what we have to our local Surface machine. We do this to keep the amount of regression testing to a minimum.
• Before we deploy to the client environment, we must validate the work items against the local surface machine. This ensures that we use the same installation media, and use the items in our Surface column as a list of regression tests. We are actively looking to automate our deployment process so that we can deploy more frequently.

Results so Far

There are some really interesting side-effects from implementing our Kanban board:

• The most notable impact is that our stand-ups have changed considerably. Rather than spending 15-20 amnesiac minutes trying to remind each other what each of us did 16 hours ago, we spend a few minutes reviewing the current items on the board and prioritizing next steps. We then talk about the issues. It’s a night-and-day difference from previous projects.
• Having the board highly visible on our wall simplifies communication and makes managing the tasks much easier. We get immediate feedback when a developer finishes a task because they have to get up from their desk and physically move their item to another column. And since we have an Accepted column that contains prioritized ready-to-go items, there’s never any guess work or wasted allocation trying to figure out what developers should do next.
• The visual representation of the board makes it easy to gauge the health of the pipeline. If the Accepted column is full at the beginning of the day, I’ll likely get a few extra cycles to focus on development tasks. If the Accepted column is low, I can quickly scan the backlog and determine if we’re going to have any issues.
• There’s some interesting metrics that come out of tracking the status of the board daily, something I’ll likely write more about in another post. But in short, I count up the number of items in each column at the beginning of the day and add a small journal note that summarizes the changes in the board.  From this I can easily track our last deployment and where the backlog changed.

Challenges

There are a few minor challenges we’ve encountered:

• From a project management perspective, it’s difficult to gauge remaining effort in hours. Although we’ve applied a sizing rank to our tasks (Small, Medium, Large – where large is 8 hours), it’s difficult to glance at the board and determine if we’ll make a target date. The Kanban eBook suggests that all post-it notes on the board should have the same weight which would solve this problem, but we are still struggling how to group and organize our tasks to fit within this concept.
• The board only works when we’re all in the office. I’ve adjusted the columns in our SharePoint list to align closely to our board, and there is some duplication of effort trying to keep the board in sync. The system that I’ve found to work best is to ensure that all tasks are born within SharePoint, and they’re considered Pending until there’s a post-it note on our Kanban board. Periodically throughout the week, I spend a few minutes updating our SharePoint list to reflect the board’s current status. The SharePoint list acts as a digital memory that can provide additional details and attachments, but the board is the most accurate representation. There are still some discrepancies between the two systems, and we either need some formal process or tweaks to make this work better.

Conclusion

For the last month, the team has been putting the final touches on a release which has involved completing some features and fixing defects. This type of work changes daily and our Kanban board has allowed us to visualize the outstanding work in a meaningful way. We’ve started having scheduled retrospectives to gather feedback and adjust our process. Generally, that feedback has been positive and we’ve course corrected a few times for the better. The true test will come shortly when we start working on the next release – will the Kanban format work or should we adopt formal sprints?

As a final word, I feel it’s important to mention the feedback that I’ve received from other teams. Some glance at our board and are intrigued, others look at the post-it notes as archaic technology and feel that our process could be brought into the 21st century with some software package. While there may be a great software package for this, the eBook warns about this – all developers will have this reaction. Our Kanban board requires no licenses, doesn’t take time to boot, responds instantly to tactile input and is always on. Besides, there is no equivalent software package that allows you to ceremoniously march a stack of post-it notes around the room as they go live.

Happy coding.