Edit: Justin Cave made a good point that this sort of communication should be up front in my quoting / estimations. Is this case, I'm still interested to know what sort of language people use to describe the 'existing code learning' activities. Especially to a company who haven't dealt with software contractors before. End edit

I have a contract to upgrade some in-house software for a large company. The company has requested multiple feature additions and a few bug fixes. This is my first freelance style job.

First, I needed to become familiar with how the application worked - I learnt it as if I was a user.

Next, I had to learn how the software worked. I started with broad concepts, and then narrowed down into necessary detail before working on each bug fix and feature.

At least at the start of the project, it took me a lot longer to learn the existing code than it did to write the additional features.

How can I describe the process of learning the existing code on the invoice? (This part of the company usually does things in-house, so doesn't have much experience dealing with software contractors like me, and I fear they may not understand the overhead of learning someone else's code). I don't want to just tack the learning time onto the actual feature upgrade, because in some cases this would make a 'simple task' look like it took me way too long. I want break the invoice into relevant steps, and communicate that I'm charging for the large overhead of learning someone else's code before being able to add my own to it.

Is there a standard way of describing this sort of activity when billing for a job?

  • nice question! it's almost like refactoring but it isn't, because there's no editing implied.
    – ZJR
    Commented Mar 23, 2012 at 2:28
  • 2
    If you are expected/required to provide a detailed breakdown then given that you have a number of features & fixes and all required an understanding of the codebase to a different degree to proceed, I would amort the cost of understanding the codebase over each of those tasks in proportion to the time taken for that task.
    – Mark Booth
    Commented Mar 23, 2012 at 16:32

7 Answers 7


I would invoice such tasks as "Review existing functionality" and/or "Review existing code". Depending on the complexity of the new features I would add a "Design xxx" task which would include the time I spend figuring out the integration points into the existing code.

I think it's a good idea to make it clear to the customer that there is some overhead in bringing a new consultant up to speed--and that, if they are happy with the result, continuing to work with the same consultant will likely save them money.

  • I have included tasks like "Learn existing code" on invoices without any issue.
    – tcrosley
    Commented Mar 27, 2012 at 23:28

Problem Diagnosis.

It's a familiar term, if you ever get your auto fixed or go to a doctor, diagnosis is a common term for figuring out what's wrong. It is also accurate, you have to go under the hood and see how everything is connected to figure out what's not working. It really is akin to working on an engine without the manual, and the company went and made the engine without looking at another engine before (so it's likely unique).

A long-winded or strangely-worded line item will get more questions which you really don't want. "Problem diagnosis" is a more or less universally-understood concept.

  • Thanks anon. Yes, I think it needs to be clear and up front, rather than half-hidden by a long winded string.
    – MattyG
    Commented Mar 23, 2012 at 2:08

Nothing on an invoice to a customer should be a surprise to the customer. Given that, I'm hoping that you already set the expectation with the customer that a significant fraction of your time would initially be spent familiarizing yourself with the application both from a user perspective and from a developer perspective. And your estimates for the first few features hopefully specified that they included a decent amount of time for familiarizing yourself with the code.

If you've already set that expectation with the customer that most of the time on the initial invoice is going to be spent familiarizing yourself with the application, it shouldn't matter too much exactly how you list it on the invoice. Use whatever language you used when providing the estimates and setting the expectations. If you're only trying to communicate this now, you've got a problem.

  • Thanks Justin, good points there. What sort of language would you use during the job quoting phase?
    – MattyG
    Commented Mar 23, 2012 at 2:01

In my capacity as a freelancer, I would probably term this something like "Knowledge Assimilation", in the general sense. And, this would have been included in any estimate provided initially to the customer.

It may not help you here, but for future reference, I suggest that you make this more of an active task in the future. For instance, invoice the customer for time you spent going through and adding comments to non-commented code, adding unit tests to untested code, etc. These are examples of tasks that add at least a little value while facilitating your understanding of the code base.

Even if there isn't much difference between reading and reading while documenting, your customer will probably have a small psychological preference for these more 'active' tasks. And, you might actually learn more by documenting someone else's code than you would simply by reading it. (This will certainly be the case if you write tests against their code).

If you do this, you can have an invoice line-item that says something like "Knowledge Assimilation and Legacy Code Testing/Documentation".

Edit: In your situation as described, I would honestly probably eat the cost of this activity. I can't speak to your financials, and I don't mean to presume, but when you're getting started, I'd put a lot higher value on racking up testimonials and pleased customers than some hours of billing. If that means an effective lower rate in the early-going, it may be a good investment. Eating some billable hours in the long run is probably a small price to pay for a satisfied customer that thinks he or she got a fair shake.

  • Thanks Erik. Great point about the code commenting; there was zero existing, so I've been doing that along the way. Yes, I agree, I've already eaten about half of the 'knowledge assimilation' hours myself, and will only be billing for the remaining half.
    – MattyG
    Commented Mar 23, 2012 at 2:06

Fixing a bug: root cause analysis.

New feature: analysis, design, integration, and testing.

Introducing new bugs: job security. :)

  • +1 for root cause analysis but -1 for the rest of the answer being a bit light on detail.
    – Mark Booth
    Commented Mar 23, 2012 at 16:27

With a client that likes to understand how things work and listens to me with dreamy eyes, I'd go with a straight Codebase Familiarization. I'd have already explained him what a stream of pain he's putting me into, and the advantage of coming to me for further upgrades.

With the other type of customer... (same treatment, but he doesn't evidently listen to a single word I'm saying) I'd go with something on the lines of:

  • Planning Phase
  • Intervention Planning

    (I'd use this one, actually, but I'd write that in Italian, in which it sounds way better)

  • Then, maybe... Solution Planning

I like the Diagnosis part of the Problem Diagnosis suggestion by anon, but the Problem doesn't sound right to me. It can be open to mild, biased, ignorant, and superficial criticism... that may leave a bad taste behind.

You know, everybody wants to throw a dart at the external consultant, and they do. (...like he wasn't good enough to understand the root of the problem while talking to them, and had to invoice his cluelessness, or god knows what)


My mechanic sends me a bill "Change oil, spark plus, check filters, tyre rotations. Fix engine rattle, road test.....

Parts (itemised),

Labour x @ $y/hour = z)

He does not break down the labour, neither should you. Bill for total hours, and describe what you did.

Not the answer you're looking for? Browse other questions tagged or ask your own question.