Code comment-training
Download as PPTX, PDF0 likes559 views
This document discusses the importance and best practices of commenting code. Comments help developers remember what their code does over time and help others understand complex logic or non-standard practices. While commenting takes extra time, it is not lazy and can help significantly with debugging and maintaining code in the long run. The document recommends choosing a commenting style and conventions at the beginning of a project and updating comments when code is changed.
Code comment-training
- 1. Ethos Commenting TrainingWeee! Commenting code is fun!
- 2. The Purpose of CommentsHelp you remember what something does
- 3. The code is just as foreign to you after 3 months of looking at it as it is if someone else wrote it.
- 4. Sometimes you just can't have great variable names.
- 5. Sometimes I don't understand complex logic just after I've written it. The Purpose of CommentsHelp someone figure out what something does
- 6. Describe why a functionality appears to go against best practices.
- 7. Bug fixing
- 8. Application DocumentationCommon Excuses for no CommentsIt takes too long, I don't have time to comment my code!
- 9. Stop being lazy! You can comment 8 hours worth of code in around 15 minutes.
- 10. The program/logic is simple, it doesn't need comments.
- 11. Stop being lazy! If everyone thought the same way the world would be very boring
- 12. If you comment it, it's more likely the developer that extends your functionality will comment their changes. Common Excuses for no CommentsI'm the only person that will every work on this code.
- 13. Stop being Lazy
- 14. Since you can see the future, can I have lottery numbers?
- 15. As stated before, code you wrote 3 months ago seems like it was written by a strangers when you try to work on it again.Comment StylesEach language has their own comment style.
- 16. Most frameworks will extend this comment style or create their own commenting style
- 17. A project's commenting style should be choosen at the beginning of the project
- 18. All developers should be the “Comment Police” to make sure everyone is commenting and following the guidelines.
- 19. 3rd party commenting syntax -JavaDoc, PyDocBest Habits for CommentingDon't comment code before you feel it's finalized.
- 20. Inaccurate comments are worse than having no comment
- 21. You don't have to comment your code before committing it to version control
- 22. Update comments for functionality you've changed. (Extend, bug fix)Best Habits for CommentingUse English for comments! This is important!
- 23. Comments are not an English test, you don't need to use full sentences or correct grammar
- 24. Most programmers can understand enough English to read and write a simple comment. Questions?