Although they are usually enforced by coding standards, and I strongly agree, I believe code comments should be minimized for many reasons:
- Except for XML comments of methods and classes, most comments are not affected by automatic refactoring tools
- Most developers forget to update comments after updating code
- Sometimes they mix with temporarily commented code
- Every one adds one or more additional lines to the source code
- They might make the code ugly
- They implicitly admit that your code cannot express your ideas
- They cannot be validated by type checking or unit testing
- Most of the times, there are more better alternatives than comments
Yet I believe they are highly needed in these cases
- Writing important messages to self or others
- Writing code review comments
- Writing //TODO tasks for self or others
- Writing failed trials to avoid reusing them later while refactoring
- Writing justification for code that might not appear logical at first look
And finally here are some cases when comments can be replaced by better alternatives
if (i >= 5) // number of orders if (numOrders >= 5) // <-- better option: use meaningful var names
if (custType == 5) // credit customer if (custType == CustomerTypes.Credit) // <-- better option: use enums if (custCredit >= 30) // credit over 30% if (OverCredit()) // <-- better option: use methods (or properties) private bool OverCredit() { return custCredit >= 30; }
if (a == b) { if (d == c) { // ... long lines of code ... } // if (d == c) } // if (a == b) // Most decent IDEs highlight matching braces when u select one of them // Also long lines of codes should be avoided, use methods
// begin saving data // ... long lines of code ... // end saving data #region Saving data // <-- better option: use regions // ... long lines of code ... #endregion SaveData() // <—- another better option: extract as method
// Modified by modeeb @ Feb 6, 2009 02:32:12 PM // better option: use a version control system that have "blame" or "annotate" functionality