When You Disagree With Your Client

March 16, 2010 — Code

Another programmer was recently looking over the code for one of my clients’ web sites and remarked that I should write about a file in my Git repository called DISAGREE. Here’s a quick explanation.

What It Is

The “disagree list” (doc/DISAGREE) is a file I maintain with my for-hire projects. It’s basically a list of points on which I disagree with the client. Let’s say the client wants to add 15 new items to the web site’s main navigation bar. I say that it’s not good idea to have so many links up there and I recommend against it. Why not create a sub-navbar or a sidebar instead?

No, these all need to be in the main navigation bar at the top, very big, OK?

Fine, I relent. I do the job and I make a note in the disagree list that gets committed to the repo along with the code. The disagree list entry has a title, a date, and briefly summarizes the discussion: what the client wanted, why I disagreed, and what alternative I proposed. It also refers to dates and subjects of emails if relevant.


In the course of technical projects, there are always disagreements. Documenting them has several benefits:

It adds a dimension to the code, providing some meta-information on top of the VCS log entries. It provides good introductory material for new programmers coming on the job, and gives you something to refer to in your code comments when you’re explaining that you “wouldn’t normally do this, but…”

It helps you feel better about your work by allowing you to take a positive action (writing prose) to counteract work which feels negative.

It keeps you honest by reminding you about when you’ve been wrong, and also when you pushed too hard to support a plan or idea that just didn’t matter that much. This kind of self-reflection helps you become a better programmer, and a more valuable team member.

It helps you gently remind the client about the times you’ve been right. Being able to quickly and eloquently defend yourself gives you some extra bargaining power in future discussions about the project. If you can refer to specific instances when the client should have heeded your advice, there is a better chance that your current position will be taken seriously.

It backs you up in case something you disagreed with goes really wrong. Fortunately I have no personal experience with this, but I imagine that if a situation gets to a point where legal action is involved, having a written, dated record of your position could help.

It lets you know when to quit. On those days when you’re fed up, take a look at the disagree list. It will remind you of the kind of discussions and behavior you’ve been around. Do the arguments seem important? Interesting? When decisions are finally made, do you have as much input as you need to feel professionally satisfied? You can easily show the list to someone you trust for an outside opinion.

In my experience, disagreements are worth documenting, and the time to document them is when they arise. Since they are often emotionally charged, memory is not reliable in recalling details. To the extent that your happiness on the job depends on the way conflicts are resolved, the disagree list is important.

comments powered by Disqus