Still we general mantra is that comments are not allowed and I can only agree with the author that this makes non standard parts of the code extremely hard to comprehend. I would definitely love to work once on an application that size with a few comments here and there.
In my day to day work I depend a lot on our test suite. If I can’t even find the tests that cover this part of the code I just break the code on my branch and let the CI tell me which tests fail. There are probably better ways to do this with test coverage tools but this method seems fairly straight forward to me.
Documentation is something we started to do recently. I feel as long as the documentation is not directly connected with the code it is hard to keep it in sync. We even have PR templates that mention to update the documentation but the shape of the documentation is just too different from the code to have a straight forward Intuition at which point it needs to be updated. What happens for us is mostly that the feature owner at some point realizes that the documentation pages are not accurate at all anymore and rewrites them.
Sadly our commit messages are 50% of the time useless so that they serve more to know who to talk to than to understand why the change was done. PRs and commit messages are great documentation I wish we would use them more. In my company the idea is more that the change should be so small that no explanation is needed but I feel this idea misses the point that code can’t explain *why* something was done.
This is definitely an area for further improvements. Are there best practices someone could point me to?