Writing Well-Documented Code – Learn from Examples
Personally I found most of those examples to be not great. I think they would be improved better names overall, more well named private methods and most importantly well structured companion test classes proving the behavior.<p>I really dont want to read another developers comments on their mental state while I am feverishly debugging their code during a 3am page.<p>The number of times I have been misled by an outdated comment. I generally open git blame to see if the comments predate any code now. Tests on the other hand almost never lie.<p>Readmes or comments explaining why something exists vs what it allegedly does are generally much better. If you can’t write expressive code why would you assume your English is much better?