How much context is the required minimum?

Question

This question got sparked by a recent discussion in the 2nd Monitor about this question: Golang Map-Reduce Master - Channels.

The problem is: How much context is needed to actually review the code in the question? How much should the reviewer assume about functions/types/object states which are referred to in the code but not included in the question itself?

In this case, it could be looked up on GitHub, because the code in the question was part of a larger project. Should this be required?

Also, the correctness of the implementation depended heavily on object state being setup correctly (otherwise it would deadlock). However, the setup code isn't included in the question. Without any mention by the OP other than "[it] passes the tests", how far should the reviewer go in assuming that everything got setup correctly? (Especially if the code could be called from anywhere, i. e. setup isn't guaranteed to be done.)

EDIT: After there had been some uncertainty in the comments, I'd like to clarify my problem. I'm mostly concerned about major dependencies.

These might be (heavy) dependencies on (at least for the reviewer) unavailable code, especially if there is some non-obvious communication going on (e.g. setting some globals that then get referenced later on) or some of the actual core logic happens there.

This could also be unstated pre- or post-conditions that would otherwise be hard to infer just from the code.

We as programmers and reviewers rely a lot on having as much context available as possible. And while it isn't required to have the whole context available to review a piece of code, a substantial fraction is. Sometimes some of that context can be inferred or some educated guesses can be made, but where is the line between not enough and just enough available information?

Answer 1

This is one area where Code Review is different from doing reviews on pull requests for your own project - because we're not immersed in the same code-base as the asker, we need a bit more help to know how and why their code is to be used.

If you know the language and any libraries mentioned, but you can't make a reasonable guess as to what the code is doing, then I'd say it doesn't have enough context. (If you don't know the implicit context of the language/libraries so well, and the question seems borderline, then move on without voting).

If there's no statement at all about what the code is intended to achieve, that's definitely lacking context - the canonical expression of this is, "I have this function; can I make it faster?" If we're to nail down a good threshold for what's sufficient context, we probably need to start from there on one side of the line, and from an unarguably complete question on the other side of the line, and see how far we can advance from those until we stop with a much narrower grey area separating them.

I try to be generous where there's doubt, and will mention in the answer if I've had to guess (e.g. "I assume that vector is actually std::vector; remember to #include <vector> for this" in C++ code, or "It's not clear whether you expect the inputs in a specific order on the stack; I'm guessing that the smallest will be at the top" in a dc program). But sometimes the whole review would be guesswork, and would have to be rejected for context.

Remember that putting a question on hold is a good thing, as it gives the asker a chance to improve it before it gets answered. But it's important to give guidance on how to improve the question, as a comment - without that, it can be perceived as unwelcoming (to use a currently topical term). I've seen many incomplete questions resurrected in much better form, so let's take care to guide and encourage their askers!

Answer 2

I think that an excerpt from my answer to Thomas Ward's meta question provides a good starting point for nailing down the whole "context" thing.

This is how I feel about context personally.

This may or may not be how Code Review feels as a community

---

The Last Piece of the puzzle

Context.

This seems to be where most of our contention is when closing questions, we need the Context thing nailed down a bit more.

My thoughts are that if there is enough, for someone who knows the language and the libraries that are being used, to understand what the OP is trying to accomplish and the post fits all the other on-topic reasons, then let's review it.