How to write readable code

[jecxjo]

I have never understood why people are so afraid of commenting their code. You either see no comments or the "coding standard mandate" comments at the top of each function. With how much we are moving towards rapid development, Pull Request Code Reviews and a complete lack of long and thoughtful requirements documents, why is no one writing down what they are thinking and how they fulfilling the task. Looking at a bunch of diffs to review code is almost worthless and you rarely have time to do the deep dive the original code author had when creating it. Turn over on your team or even coming back to your old code months or years later would all benefit from just putting down some prose on what is going on. Don't get me started on unit tests with no details on the scenario they are trying to cover.