Ask HN: Over the shoulder Code-Review in remote settings

If something’s super complex, and I don’t feel like it’s the submitter’s fault, or even if I’ve got a PR where I realize the code I’ve written isn’t optimal, and async feedback would be too slow, I’ll usually schedule a meeting on someone’s calendar, giving them at least a day of notice.

But otherwise? If I can’t understand what’s going on without too much difficulty, that’s on the PR submitter to improve their code readability through structuring, naming, comments, or as a last resort, external documentation imo. So I see not having the original submitter involved as a feature. Who knows if they’ll be around when you have questions about the same code in 2 years? Is someone going to document everything that was said in the “over the shoulder” review?

That being said, the work I do isn’t anything cutting-edge. More complex code justifies more involved review practices.

You could solve this with devcontainer.json and using tools which support this such as Codespaces or Codeanywhere. In addition in Codeanywhere you can share the screen from inside the IDE, have collaborative terminal or code sharing with location following.

I've found out that while over the shoulder code review is good, pair programming (in remote settings or not) is even better. Then you can exchange feedback while coding, which can be more effective than a code review. There are multiple tools like Codeanywhere or Code-With-Me (IntelliJ IDEA), Liveshare in VSCode, etc. that facilitate remote pair programming.

I am heading a couple of teams who are also now fully remote and what I usually see is that the engineers make fairly small and self-contained PRs. Those *generally* don't call for a over-the-shoulder code review. Keep in mind that we simply never merge code without a code-review regardless of how small the change is, so most engineers in our organization use small, easy-to-digest PRs in order to make it easier for their colleagues to reason about the change.

If you find that a PR has attracted a lot of comments and back-and-forth discussion, it's good to encourage the devs to jump on a call or go to a meeting room to try to clear it up synchronously by talking it out. One thing to always consider is that in a fully remote setting you probably don't want to have a lot of those talks going on all the time as they can be fairly disruptive and time-consuming. Having lots of those meetings can be a sign of a couple of things:

- maybe the PRs are too big to digest and create lots of questions

- or maybe team members were not on the same page about the implementation BEFORE coding

- or (rarely) your teams don't have an agreement on consistent coding practices. For example: back-and-forth about tabs vs spaces, linting, or ways to do repeatable tasks like logging or class/variable naming, etc.

TLDR;

- Always requiring a code review for every PR is a good thing. With time your team will work well and everybody's gonna be knowledgeable what others are working

- Keep PRs/code-changes small. That reduces the need for over the shoulder-code-reviews which most of the time can be substituted with a simple approve on the PR

- Over-the-shoulder code reviews are good but pair-programming sessions (remote or not) are even better

- If you do have to jump on a call about a code change, that shows that maybe some of the above things didn't work out. Still go for it as soon as you find out async comments on the PR don't work

Why don’t you install the GitHub Slack application? It will tell you immediately when somebody asks for a review and it has other useful functionality as well.

On the whole I prefer it to 'over the shoulder' I think - 'no that bit, where I'm pointing but you can't see, gah' is annoying, but I get my own screen to look at.

(Even better might be some kind of remote editor session, so I could connect from whatever editor I like to use, on my screen at my resolution with my colours, and see your cursor move around while you talk. No idea how you'd do that in a cross-editor sort of way, though I suppose you could support major ones in a way that enabled them to be used with each other, e.g. I view in vim while partner moves cursor in VSCode or whatever.)