It's one message I struggle to convey to people I do code reviews for: don't make me understand it, make it more self explanatory so every reader does. (And, yes, I ask for it explicitly too)

(I sometimes "ask" questions for something it took me a few back and forths through code to get so they'd think about how it could be made clearer)

Unfortunately, most people focus on explaining their frame of mind (insecurity?) instead of thinking how can they be the best "teacher".

▲

hakunin 9 days ago | parent | next [-]

Yeah, not easy, but it helps to build some rapport first, so people learn what you’re after. The way I tend to do that is by leaving a review comment with an example code snippet that makes me understand it better, and a question “what do you think about this version? I tried to clarify a few things here.”. + Explain what was clarified. I find the effort usually pays off.

▲

necovek 9 days ago | parent | next [-]

I found that to be a double edged sword: some copy and paste it verbatim without thinking it through and adjusting at all.

It's a delicate balance we need to keep in mind between many of:

- maintainable code

- getting things done

- feeling of accomplishment

- feedback loop speed

- coaching

- motivation and emotional state ("why are they pestering me, the code works, I just want to feel productive and useful: this was hard enough to get right as it is")

...and more!

At the same time, some do get the point, but getting readable code is really an art/craft in itself, and nothing but experience and learning to look at it from outside is the main driver to learning.

	▲	hakunin 9 days ago \| parent [-]
		Yeah, this does require a certain team culture building effort. Just starting cold without any expectation-setting might not be received well. One "rule" I try to meta-promote is — working code is the first step, and a great foundation to then proceed to clear and maintainable code. Another, is that code reviews are first-class citizens deserving mindfulness.

▲

radiator 9 days ago | parent | prev [-]

But this might require too much effort from the reviewer

▲

kristianbrigman 8 days ago | parent | prev [-]

One relevant side effect: AI seems to understand your code better when you do this as well.