Sunday, March 03, 2024

Lack of nuance

 No nuance is almost always incorrect!


Yes, "almost" is very important in that statement.


If you get a response/answer/instruction without any acknowledgement of the nuances, you're almost certainly not getting the full picture. 

How do you know the importance of what is missing, if you don't know what's missing?



Saturday, March 02, 2024

Friday, March 01, 2024

Wednesday, February 28, 2024

Reviewing documentation is like reviewing code

 Two quick, but key points.


1. What is it meant to do? And, where/what/who is it for?

You can't review code fully unless you know what it's meant to do. You might be able to point out if something doesn't compile or account for an edge case that hasn't been covered, but if you can't say if the code does what it was meant to do, you can't provide a useful review.

It's the same with documentation. If you don't know what the document was intended to achieve, communicate, or teach, how do you know it is correct, appropriate, or does what it's meant to?


2. Take advantage of tools before you involve people.

Use spelling and grammar checkers before asking someone to review it.

It's like asking for a code review on code that doesn't compile or meet coding standards.



Tuesday, February 27, 2024

"LGTM" isn't automatically a bad code review comment

What's the reason for doing a code review?


It's to check that the code does what it is supposed to and that the reviewer is happy to have it as part of the code base.


If the code changes look fine and the reviewer is happy, they shouldn't be expected or obliged to give (write) more feedback than is necessary.


What's not good is pointless comments or references to things that weren't changed as part of what is being reviewed.


A reviewer should not try to prove they've looked at the code by providing unnecessary or unnecessarily detailed feedback.

It's not a good use of time for the person doing the review.

Dealing with (responding to) those unnecessary comments is also not a good use of the time for the person who requested the review.


Writing something, even if it's a few characters (or an emoji) that indicates that the approval wasn't fully automated or done by accident is fine by me.

Of course, if all someone ever did was comment on code they're reviewing this way then that should raise different concerns.



Don't write more than you need to or for the sake of it.

Don't comment just to show you've looked at something.