Code comment-training


Published on

Some no-brainers on commenting your code

Published in: Technology, Education
  • Be the first to comment

  • Be the first to like this

Code comment-training

  1. 1. Ethos Commenting Training<br />Weee! Commenting code is fun!<br />
  2. 2. The Purpose of Comments<br /><ul><li>Help you remember what something does
  3. 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. 4. Sometimes you just can't have great variable names.
  5. 5. Sometimes I don't understand complex logic just after I've written it. </li></li></ul><li>The Purpose of Comments<br /><ul><li>Help someone figure out what something does
  6. 6. Describe why a functionality appears to go against best practices.
  7. 7. Bug fixing
  8. 8. Application Documentation</li></li></ul><li>Common Excuses for no Comments<br /><ul><li>It takes too long, I don't have time to comment my code!
  9. 9. Stop being lazy! You can comment 8 hours worth of code in around 15 minutes.
  10. 10. The program/logic is simple, it doesn't need comments.
  11. 11. Stop being lazy! If everyone thought the same way the world would be very boring
  12. 12. If you comment it, it's more likely the developer that extends your functionality will comment their changes. </li></li></ul><li>Common Excuses for no Comments<br /><ul><li>I'm the only person that will every work on this code.
  13. 13. Stop being Lazy
  14. 14. Since you can see the future, can I have lottery numbers?
  15. 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.</li></li></ul><li>Comment Styles<br /><ul><li>Each language has their own comment style.
  16. 16. Most frameworks will extend this comment styleor create their own commenting style
  17. 17. A project's commenting style should be choosen at the beginning of the project
  18. 18. All developers should be the “Comment Police” to make sure everyone is commenting and following the guidelines.
  19. 19. 3rd party commenting syntax -JavaDoc, PyDoc</li></li></ul><li>Best Habits for Commenting<br /><ul><li>Don't comment code before you feel it's finalized.
  20. 20. Inaccurate comments are worse than having no comment
  21. 21. You don't have to comment your code before committing it to version control
  22. 22. Update comments for functionality you've changed. (Extend, bug fix)</li></li></ul><li>Best Habits for Commenting<br /><ul><li>Use English for comments! This is important!
  23. 23. Comments are not an English test, you don't need to use full sentences or correct grammar
  24. 24. Most programmers can understand enough English to read and write a simple comment. </li></li></ul><li>Questions?<br />