Blog / Go Language Spec

Why is context.TODO not just a comment?

July 21, 2025

I’ve been on vacation for the last week, so haven’t written much. Let’s finally finish up the context package series with some reader feedback and questions!

Joost Helberg wrote in with an interesting observation about context.TODO. In his own words:

With regards to context.TODO, back in my early Go days, I thought the TODO was about the intent of this context. Like context.Background is for a background task and context.WithCancel for a job that can be canceled.

But the TODO is actually about the programmers intent! The same syntax level, but for a completely different abstraction. I though comments where meant for this: // TODO: find the right context for this.

I was (and am) very enthusiastic about Go as a programming language, but this mixing of abstractions in a package API was a bit off putting. I can think of a lot of TODO() methods in lots of packages to serve the same purpose; and nobody does that. Of course not, it’s confusing to mix abstraction levels.

What’s your take on this?

I think Joost is right about this. context.TODO conveys a different type of meaning than context.Background or context.WithCancel. I think a strong argument could be made that context.TODO “should” be replaced with context.Background plus a comment.

So why did the Go team make this particular decision?

I can’t read minds, and I wasn’t present at the time the decision was made, but I can make some educated guesses.

Comments cannot be (reliably) examined with static analysis tools. Package-level symbols, such as context.TODO, can be.

Is that enough justification for a separate package level symbol? I suppose this is a matter of opinion. In the early days of the context package, it likely was. Virtually all code would have used context.TODO somewhere, at least for a while, during transition. Now nearly a decade later, the case may not be nearly as strong, but by now we’re stuck with it.

It would be interesting to see if there are other examples of this in the Go standard library (or external libraries). I’m not aware of any, but if you are, please let me know!

Share this

Direct to your inbox, daily. I respect your privacy .

Unsure? Browse the archive .

Related Content

context.TODO

We’re almost done going through the context package. What would you like me to cover next? If you have a suggestion, hit reply, and let me know! – func TODO func TODO() Context TODO returns a non-nil, empty Context. Code should use context.TODO when it’s unclear which Context to use or it is not yet available (because the surrounding function has not yet been extended to accept a Context parameter).

context.Background

After this detour through context key types, let’s get back to the GoDoc for our context package. Next up: context.Background(): func Background func Background() Context Background returns a non-nil, empty Context. It is never canceled, has no values, and has no deadline. It is typically used by the main function, initialization, and tests, and as the top-level Context for incoming requests. Why would you ever want a context that essentially does nothing?

Canceling a context

I’m jumping out of order a bit today, to cover a more basic function first, before the more advanced version. Bear with me. func WithCancel func WithCancel(parent Context) (ctx Context, cancel CancelFunc) WithCancel returns a derived context that points to the parent context but has a new Done channel. The returned context’s Done channel is closed when the returned cancel function is called or when the parent context’s Done channel is closed, whichever happens first.

Get daily content like this in your inbox!

Subscribe