Your SlideShare is downloading. ×
Code comment-training
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Code comment-training

392
views

Published on

Some no-brainers on commenting your code

Some no-brainers on commenting your code

Published in: Technology, Education

0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
392
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
1
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. Ethos Commenting Training
    Weee! Commenting code is fun!
  • 2. The Purpose of Comments
    • Help 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 Comments
    • Help someone figure out what something does
    • 6. Describe why a functionality appears to go against best practices.
    • 7. Bug fixing
    • 8. Application Documentation
  • Common Excuses for no Comments
    • It 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 Comments
    • I'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 Styles
    • Each language has their own comment style.
    • 16. Most frameworks will extend this comment styleor 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, PyDoc
  • Best Habits for Commenting
    • Don'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 Commenting
    • Use 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?