Hacker News Reader

Comment by jrootabega | Hacker News Reader

This is why, when a colleague has a question about a pull request, or my feedback on THEIR pull request, I push us to have the discussion in the PR comments, instead of the pernicious "I just have a few questions, it will only take a few minutes" that always adds up to more time and attention than people claim. There ARE often situations where opening a synchronous communication channel is necessary, but even then, you need to capture your discussion and agreements publicly. Commit messages and PR discussions are "hyperdocumentation".

Some people get it. But overall in the cultures I've done it in, it mostly gets me branded as difficult.

View on HN

I have mostly seen juniors/other people who lack self confidence are the ones who most want to push code reviews into “quick chats.” I’m happy to help when they are very new so I can explain a bunch of things, but it really frustrates me when people continue to do this long after joining.

I also think it shows a fundamental misunderstanding in what code review is - half the time I’m basically not invested at all in the outcome of the particular review, I am just giving my time and knowledge to help make sure that we produce good code. When people start these sync chats I have to context switch a lot and people often think I’m super opinionated on the outcome (so ask me lots of open ended questions I’m not prepared to answer), which is not what I intend to convey when I say you need to test something or document some particularly confusing part because it seems pretty likely to break.

If you explain your motivations well (& politely & thinking about their POV), I suspect you'll not get that branding.

"Hey, sure I can answer your questions, but I often find it helps to do that in public so we have a track record... etc. etc. And I'm not immediately available, so I'll get to it soon..."

Yeah, that's necessary, but I think there are cultures and situations where it's not sufficient, unfortunately.

Good suggestion. Adding...

It's tough to fight habit and culture. As the article points out, it's *all* about comms. That's a 101 statement. Having to explain the value of comms (and documentation) isn't something you should have to do. So if you are, chances are good they won't get it.

Yeah, and: if people resist, then let it be. It would've been better, but it's not important enough to sour relationships about, even if just a little bit.

> Some people get it. But overall in the cultures I've done it in, it mostly gets me branded as difficult.

Sorry to hear that. Getting the right balance of sync and async, and knowing when to use one or the other makes a big difference. In my current team we went through multiple iterations to come to a mix that works for us. If it's too much sync, the constant sync conversations drain you; if it's too much async, coming to a concensus becomes grindingly slow.

I have learned that its good to praise in public, criticise in private. It is possible to have criticism in PR's private inside a company which reduces its "publicness" but some people are still sensitive even with the reduced exposure.

I hate that idea. If I criticise an idea in public, and I'm wrong in my criticism, then five other people will immediately correct me. Or provide nuance and perspective I miss.

Also with private criticism, any decision tends to gravitate toward the opinion of the highest paid person. If the debate happens in public, everyone has more of an equal chance to be heard.

----

Edit: almost forgot! Private criticism also leads to an air of suspicion, in my experience. When everything public is upbeat and positive you start to wonder what terriblenesses people are hiding. It might be nothing, but that's the thing -- you just don't know.

Being able to publically discuss both the good and the bad is a prerequisite for a smooth operation, and the hallmark of a mature organisation.

This is the biggest part of life that people just don't get and has always bothered me.

I can't stand people that are always-positive and nice all the time. I know they are lying and holding stuff back --- but what? I'd rather be friends with someone honest than nice. At least I know what they are thinking, and thus actually know them. Some people would rather just go through life in a mask and insist everyone else wear one too -- something I generally refuse to do.

> Also with private criticism, any decision tends to gravitate toward the opinion of the highest paid person. If the debate happens in public, everyone has more of an equal chance to be heard.

Interesting, that's the opposite of what I've experienced. Also a problem with group dicussions is that it's too easy for participants to drift into group think and conformism. I thought these are general principles, but maybe they are predicated on the group.

> Also with private criticism, any decision tends to gravitate toward the opinion of the highest paid person. If the debate happens in public, everyone has more of an equal chance to be heard.

This. When I get criticized in private on an technical matter by someone more senior than me and disagree with them there isn't much I can do. Maybe I already have a good relationship with them and we can talk it out but if not I just have to suck it up. I can maybe escalate to higher up but that is also very risky and might more harm than good.

There isn't much I can do to defend myself.

In public there is a chance of other people offering their opinion. Senior people might get kept in check if their critic seems too unreasonable to the rest of the team.

I think a good rule is to criticize technical stuff in public and personal stuff in private.

Some people are insecure and terrified to ever have a record of them being wrong or ignorant. That's understandable, especially in cultures that hire a lot of relatively unskilled people and h highlight that they're competing. I think it's essential that those who are considered senior or expert demonstrate their own vulnerability by asking questions that show they don't understand or know about something, and being grateful for the response.

If and when you have that trust, criticism also needs to be more structured and question oriented. E.g.

- I think the main problem we're trying to solve is X. Is that right?

- if we do this, we'll solve Y but we'll also have a new issue Z. Do we think we would rather have Z than Y?

Most actionable code review comments are criticism. People have to be able to avoid taking criticism of their code personally, and to write criticism in an inoffensive way.

The whole team should be able to look at and learn from code reviews, and the best way to do that is if it's in the open for the whole team or company to see. I'm not sure if truly "public" is possible for most companies, so I'm not talking about that.

I would say that you're right about other kinds of feedback, like criticism about (mis)conduct, attitude, etc. That should for sure be done in private.

I also have learned that people that worked long time with toxic people, or are the toxic ones that are more sensitive to this. One starts being afraid of openness.

It's hard - but a wonderful soft skill - to do this in semipublic envs and be gentle.

"enhancement: Extracting the lines below into a separate function. As far as I understood it's only calculating x, you can call 'x_calculation'. Fell free to use a better name than my suggestion".

shorter, for a team that you are already know for some time:

"enh: extract into a new function. It's calculating x, maybe it's 'x_calculation'. You can name it better than me."

During retros then, I usually recall everyone that I'm open to be criticized in good terms, and send me a message if I'm out of touch. Or even be open during the retro.

True. And I guess you need to be prepared to favor sync at first for newer problems and colleagues. Once you understand each other better, the ambiguity of content and tone in async lessens.

Actually, I suspect some people don't like to write and/or read; for some it might even be stressful. Not everyone is an author, and at a smaller scale not everyone is comfortable with written communication. It is true that is more difficult than interactive Q&R.

That goes for speaking too, though. A lot of people are bad at/uncomfortable with speaking/listening. This just highlights using one's strengths rather than forcing the usual one-size-fits-all.

I understand anxiety, but at a certain point, we, as an industry, need to put our collective foot down and say that an ability to communicate efficiently in written-form is a mandatory qualification for success.

I really despise working with people who behave like this. The main problem is this turns the disucssion into written and asychronous. On a phone call there is so much more nuance, so many more questions that can be asked and so much more information for both parties.

When it's just async written messages, I'm constantly only able to say 1/10th of what's on my mind only for it to be misunderstood by the other person hours later. Sure you can blame it on me for being poor at written communication but I'd argue the other person is always just as bad too. They just think it's the other person and not them.

I have the opposite feeling. It's so much more convenient and efficient for me to communicate in text, largely because I can gather my thoughts and present them in a structured fashion. Which then becomes a reference as needed.

Also it helps you both look back easily at goals and tasks that were defined in-conversation.

I am on the opposite end of these questions and feel quite differently. Code review tools are great at letting you ask questions about specific parts of the code. And they leave a record so you can go back and show someone else the discussion/others can follow.

It’s also, not necessarily disrespectful, but a very inefficient use of my time to spend 20 minutes chatting with someone about why you need to add a test in XYZ and make sure you check A - when I can do that in just a few minutes exactly when I’m ready otherwise. Because I am reviewing 5+ peoples’ code and have my own things to do as well. The asyncness is necessary for me to manage my time. I can also read much faster than I can listen, and it takes me longer to explain something with words than to find a couple links and write out a few sentences about something.

I'm back in a team setting again - we've got face-to-face, Slack, Teams / email, and Gitlab as communcations channels (too many different ones for my liking), and I'm already noticing how everything important seems to have to be repeated 2-3 times; there's the informal one to one, there's stand-up and other meetings, and then usually someone isn't around due to holidays or working part-time and they have to be caught up first.

If these things were written down there might be less of them. Might. It might just be part and parcel of working in a more enterprisey setting again.

I once joined a team and in my first face to face meeting the person who was the technical leader was upset in a meeting that “people are still doing this process wrong”.

Being new-ish I felt like I could ask the obvious question.

“Where do we find this process?”

Leader: “Oh don’t worry, I’m not blaming you. I sent out the process in email before you joined.”

“I joined nine months ago.”

Leader: “Yup.”

In the end this person was actually pretty great to work with but man having a ton of wonky communication methods and etc just constantly causes problems.

Not just that, but the version control system is an actual system of record, while your chat system isn't.

But people get lazy because Slack is there and it's "easier" (really, more immediate) than looking at the PR.

Would be cool if comments to PR in Slack were transmitted to Github.

Opened a feature request: https://github.com/integrations/slack/issues/1433

Yeah, not sure why people like to take PR discussions private so much. One workaround is to just post summaries of the private conversations as comments after the fact.

"Discussed A, B, C with <@person> and we agreed on <plan of action>"

Honestly, that does sound difficult. I get what you're trying to achieve, but if I'm trying to land a change, having a synchronous conversation (ideally in person) will resolve any misunderstandings between us on the order of minutes. Having an asynchronous back-and-forth takes on the order of hours or even days. And what do you get for your time? A nice record you can look back on? What are you going to use that for? Most changes likely aren't ever referenced again. Even if you, by some small chance, look back on a specific change and find the record missing, you just go "oh well, I guess we won't know exactly why that was done" and move on your with your life.

Let's not forget that you can go in both directions. If you capture what you want to talk about publicly, you still have the option of having a private direct conversation about that. I agree that blindly following public-only-async-only all the time is not good. I just happen to think that the balance is unfairly and unhealthily tipped towards the direct interruption pattern.

I think a lot of the effort that people perceive has to go towards async discussions is actually just resistance effort, too. When multiple people embrace it it can be surprisingly easy.

And a lot of times people push the async method because the environment is already difficult -- for them. Sometimes certain team members get bogged down in focus work and want to get that done as much as others want to have a discussion. How to have good conversations in the ideal workplace is one thing; how to have them in more dysfunctional situations is another.

It is certainly the case that in most archives, most messages will never be looked at again.

This is the price we pay for not knowing what's going to be important in the future. If we knew that, we could mark the messages immediately and have them pushed into the FAQ or the wiki or whatever.

By obvious corollary, message archives need good full-text searching or else they are useless.

Our team includes a technician. One of his jobs is to copy important info from email threads to the FAQ wiki. We have a policy to not use one-on-one messages for anything that should be known by the larger team. I preach bus problem avoidance so I am totally on board with that policy.

If you work on a healthy team, public comments are better from my POV.

I can remember many times, specially on new teams that I just joined, that by reading PRs, specially following https://conventionalcomments.org/, I get much faster the motto and the spirit of the team.

You have the context and the focused discussions on the same place. You can also check how much time it took to deliver and even connect easier to the outcomes of the deliverables.

If the discussion gets too subjective, use the team private chat, with threaded comms, then a direct call.

I know it depends on the urgency as well, but we should strive for general efficiency, not efficiency only during rush / at the end of sprint.

That's why also I prefer to open WIP PRs with incomplete code. Open discussions beforehand.

Also, repeated questions and similar problems can be retrieved from the chat / comments history.

Now, for early designs, spikes, initial research on an epic/hard tasks, needs some sync comms, followed by some asynchronous comments and questions.

Even things like "yesterday we discussed during a call x, y and z, and we agreed on w. it still holds up? In this case, I will use the strategy N to develop the solution, please comment back if you changed your mind".

It helps me a lot, and the people that I asked about this kind of message are heavily positive on it, because it's neutral enough and consolidates the agreement.

Then after a few weeks working close to someone (same team, for instance), I can make that phrase shorter, because we established a protocol.

Now that said, under my new contract, the entire team is almost silent on chat and everything is a direct call with 4 people on avg. I'm wrecked today because of 5 consecutive 30min~1h meetings to sync information yesterday.

I'm happy that you haven't made the opposite experience.

> if I'm trying to land a change, having a synchronous conversation (ideally in person) will resolve any misunderstandings between us on the order of minutes.

That does not match with my experience.

Imagine I wrote a comment on Steve's PR in foo.py line 31 that said "I see what you are doing here. Do you think this would be more readable if you used the itertools from the standard library instead of implementing this yourself?".

Now Steve asks me if he can have a call with me about my comments. I join the call and he opens the PR. He reads my comment aloud, then he says "OK" and opens up the documentation for itertools and reads it silently. I'm still in the call.

This goes on for every comment.

I see what you mean and wish that that was how it worked - and I've made good experiences doing this after 90% of comments in the "written comments" stage are worked on by the author. But just skipping it sounds like insanity to me.

Why would someone join a call to read you the itertools documentation? Seems like a very contrived example. If it were possible to use itertools, wouldn't they just research that, update the PR, and say OK in a comment? The fact that itertools was used for the implementation is not something that even needs to be documented as part of the "public discourse"

> Seems like a very contrived example.

It was based on my real-life experience working with a colleague from another team.

> If it were possible to use itertools, wouldn't they just research that, update the PR, and say OK in a comment?

Time spent on a call is time you are publicly perceived as working. Time you spend researching itertools is time during which someone can interrupt you by pinging you in Slack. In that employee's shoes, it seems clear which one of those gives you less of a headache at the end of the day.

Politics aside: Exactly what you describe - the capability to research a library, respond to a PR comment concisely and appropriately - are skills that no one learns during a CS degree, nor doing code monkey work. Ideally, this is the sort of thing a junior engineer gets taught during their first years on the job if supported by a capable mentor. But if they don't have one? Tough.

> Time spent on a call is time you are publicly perceived as working. Time you spend researching itertools is time during which someone can interrupt you by pinging you in Slack. In that employee's shoes, it seems clear which one of those gives you less of a headache at the end of the day.

I think you have a very strange view of development work. At least in my experience, a vast majority of work involves going off on your own and implementing things, which often involves reading documentation. Meeting with a colleague is also considered work, but I wouldn't say meeting with a colleague is somehow considered "more work like" than solo development or that many developers prefer one form of work over the other.

> I think you have a very strange view of development work.

I did not present my view of development work - I presented that employee's view of development work.

> At least in my experience, a vast majority of work involves going off on your own and implementing things, which often involves reading documentation. Meeting with a colleague is also considered work, but I wouldn't say meeting with a colleague is somehow considered "more work like" than solo development or that many developers prefer one form of work over the other.

In my experience, every single developer wishes they could spend less time in meetings and more time "doing real work" (their perspective, not mine). Everyone with the opposite view is promoted out of being an Individual Contributor.

I agree. The only thing that matters is the change that ultimately gets committed. It’s rare enough to need to go through the commit logs, but optimising for this instead of optimising for getting the job done quickly and well, makes no sense to me. And anything contentious or tricky should be commented in the code itself.

There is a place for everything - PR comments, public slack channels, private DMs, in-person meetings, video calls, 1:1s - even phone calls! - but what’s critical is to use the tool that best gets the job done. And most of the time the job is not “teach everyone all the time”.

Very relatable Let me know where you end up that people appreciate it and I'll come join you!

Reply on news.ycombinator.com