メシのタネ

メシのタネになる、AIや技術総合情報のサイト


When Code Feels Off, Turn It Into a Question


  1. English
  2. When Code Feels Off, Turn It Into a Question
A graphite tangle on a notebook resolves into three clean lines.

広告

日本語版

Ever look at a pull request and think “something's off,” then blame yourself because you couldn't write a good comment explaining why? I used to do that a lot. Lately I've been less sure that the whole problem is mine to solve.

Of course you owe people an honest attempt to explain what you see. Sometimes that's enough. Sometimes the design and the reviewer are starting from different assumptions, and no amount of polishing a Slack message is going to surface them.

“This is hard to read”

I can tell what the code does, but I can't find the bit where it decides whether a user can see something. The fetch, the eligibility check, and the response formatting all sit together.

I think the core job here is deciding what this user can see. I'm having trouble tracing that decision through the data fetching and response shaping. If we expect more conditions, would it make sense to give the decision a name and test it separately?

That gives the author a place to look. “Unreadable” gives them an adjective and a bad afternoon.

“This design feels like a lot”

Maybe the layers are there to support future extensions. I can ask what extensions we expect and what we gain from paying the initial and ongoing cost today.

Which extension do we expect to add first? If the current requirements only need one path, I'd like to understand what we gain by introducing these layers now.

If there's a concrete answer, great. If all we have is “we might need it,” we can talk about the cost of the abstraction.

“What does this test protect?”

A test can pass while the user-visible behavior is wrong. If it's mostly checking that internal calls happen in a certain order, I try to name the regression I'd actually care about.

What should this feature guarantee to the user? If we break that guarantee while leaving these calls in place, will this test notice?

That question often gets us to a better test. It can also uncover a perfectly valid reason to care about the order, which is useful to know.

When I'd get out of the comment thread

A spec can be correct on paper and a pain to operate. Say the normal case is straightforward, but a frontline team has to handle exceptions manually. I could guess how often that will happen and write a little dissertation in Slack. Or I could ask the people who are going to do the work.

  • How often do we expect exceptions here?
  • Who handles them, and what do they have to do each time?

A team that can have that conversation is doing something right. If Japan's Ministry of Economy, Trade and Industry ever opens a public consultation on getting better at code reviews, somebody let me know.

So where does that feeling come from?

It's usually a gap between what I expect, given the purpose as I understand it, and what I see in front of me. My expectations are shaped by projects I've worked on. The person who wrote the code is working from other constraints and assumptions that may be invisible to me.

There's a bit of transcendental idealism in the way I think about it. Each of us interprets what we see through categories we already bring to the work. You can leave the philosophy there and still ask what shaped the other person's reading.

I can be missing context. The design can be missing a premise. We can both understand the trade-off and genuinely prioritize different things. Once we put those assumptions next to each other, the feeling has done its job. It got the conversation started.

I think that's how good software gets made, anyway. Ask me again the day after a particularly bad review.

Q&A

What can I say when I can't explain why something feels wrong?

Start with what you thought the code or design was supposed to do, then name the first thing you observed that didn't fit. Make room for the author to tell you which premise you're missing.

When is a conversation better than a written comment?

When the answer depends on operational details, ownership, or several assumptions you can't verify from the diff. Ask the people involved about the specific scenario, then leave a short written record of what you agreed.

Does a different person write these posts every time?

Same person. Different mood. I'm in a pretty good one today.


コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。