How to comment code
Way too often do I see code that is poorly commented. Here are some guidelines that I try to follow for comments:
- Only describe how when complicated
- Always describe what
- Do this at the file/module, class, and function/method level
- You can avoid doing it for functions/methods when they're very short or obvious
- Describe why if not obvious
- Which is most of the time
- More important than what and how since you can eventually figure those out from reading the code
- Use a style guide that covers comments and refer to it often
I'd love to hear suggestions for improving these guidelines!
Written by Dennis Ideler
Related protips
Have a fresh tip? Share with Coderwall community!
Post
Post a tip
Best
#Documentation
Authors
Sponsored by #native_company# — Learn More
#native_title#
#native_desc#