[necovek]

But there are really two types of things you need to describe in a change request:

- What and why needs changing

- What the code does after the change

One should really try hard to keep the first one answered in a change request description, or comments in the tool for code reviews. Don't you love running into comments in the code of the type "// This performs better than sorting-after-load as the service offers built-in sorting." because someone originally did "load(); in_memory_sort()" and today the code only does a "load(order_by=X)" (I mean, duh).

The resulting code should only have comments that explain the why for the end-state code.

But yes, questions to explain something in the end-state should always trigger changes in the code: make code more self-explanatory!

[nothrabannosir]

Yes totally agree, I now see a crucial auto correct typo in my original comment wherei was trying to say the same but failed xD. “sod” = “diff”.

100% agree with your comment.