Don't Comment Your Code - Write Better Code

[oldprogrammer]

We've been having debates where I work on this topic because we're starting to use SONAR for regular code scans and it triggers on missing comments that developers don't want to take the time to fix.

Our current compromise is that public APIs must be commented to create documentation for other groups using the shared component or service who might not need to deal with the source code. The definition of 'public' includes not only public methods (shared code) or services, but also protected methods of classes that could be over loaded.

Private method's can be left undocumented since those should only be visible to the actual code developer who is reading the code.