TL;DR; Should I explain to junior developers that I'm being scrupulous during code reviews because our boss asked me to help them improve their code quality, and not just because their code sucks for technical reasons?
(I don't really say "your code sucks" during code reviews, this is just a TL;DR; version. The long version typically goes along the lines of "I think X should by Y because of Z, and also this and that".)
I am a senior developer in a large organization with a somewhat formal employee performance evaluation process. In my current project I play a lead role for a handful of junior developers, organizing sprint planning and software design, conducting regular code reviews etc. It's a small team so typically all are present at every activity.
At the start of the project our manager, in a private conversation, asked me to help ensure those junior developers improve the quality of code they write, things like following style guides, adding useful comments and JavaDoc, creating thorough unit tests and such. I'm assuming this will be taken into account during their performance evaluation later.
As a result I've been trying to be quite rigorous in my code reviews, and I suspect some of my comments might have been seen by some of them as unnecessary nitpicking1.
Sometimes I meet certain resistance to my suggestions and I have to spend quite some time explaining why we need proper JavaDoc and concise method names, and why we should fix the code now and not "later". I can successfully get my points across with technical reasons, and we reach the state that seems acceptable to me, from both points of view: we get the code quality we need to deliver a proper product, and I help our manager to meet the goal of helping the junior colleagues to grow.
I think that if the junior devs knew the deeper reasons for such thorough code reviews we would spend less time arguing about them and more time working towards our target release date. So, the question is, should I explain to them the "political" reasons for my rigour, or stick to the technical reasons? Or would it look like an attempt an an "argument from authority"? If I should, would I do it in front of the team, or approach each person privately?
1 - Some examples:
- A class constructor JavaDoc has
@param <name>
but no description, so I insist they put a useful description for each parameter. - A comment inside the code is vague and unclear, so I suggest they either remove it if it's unnecessary, or change it to something more useful.
- A method of an
Apparatus
class has a single method to shut it down, calledshutdownApparatusSafely
, so I suggestshutdown
should be sufficient (more concise and to the point).