I recommend adding these types of comments when writing code:
- Classes: A brief description of the class purpose.
- Functions/methods: A brief description of what the method does. It’s also good where possible to provide descriptions of the expected parameters and return value if applicable.
- Properties: A brief description of what the property is for.
- Most code has some logical grouping as it flows. Add a one or 2 line comment before each section describing what’s happening.
- If you write a complex piece of code/algorithm/fluent method chaining, add a description of what’s happening. Sometimes it’s difficult to determine what’s happening from the code alone.
Why is commenting code good?
- Put yourself in the does of someone who has to change the code later. Comments help other developers (and often yourself) understand what is happening, and what is supposed to happen.
- Comments are helpful in debugging errors, where the logic of the code may not match the expectations set out in the comment.
- Comments help other developers determine if a method or class is something they can use in their own code.