Comments

##Intro

• Compensate for lack of expressiveness
• Becomes rapidly lies as the code evolves
• Occasion where we feel we need to comment on something is rather a good instance of refactoring
• Clean your code rather comment on something

Good Comments

• Legal comments, GNU license, MIT license, corporation owned...
• For informations. Ex: Regexes
• Intention explanation
• Clarifications => ask yourself if there is a better way before doing this
• Warnings
• TODOS
• DocBlock for public API => Only what is necessary
• Really important code

Bad Comments

• That are false or vague => Does it do what it says? Is it ambiguous? Is it up to date?
• That grumble => Doesn't say anything
• That are obligatory => without reason
• Used for versioning => Use a software for this please. Git anything.
• Comments that replace functions
• For positioning => Public, private, protected...
• Only doing noise => Returns, Constructor, Attributes, etc... method docBlocks
• For branching => // while, // try, // catch ...
• Dead code => Please don't. What is dead is dead
• Hard to read
• Private method doc => It's a distraction. Methods should be small anyways
• Showing errors => Correct the error instead!