Your code is like your new puppy, named Fifi (French poodle). You yourself know and love Fifi, but nobody else quite understands what tricks Fifi can do and how Fifi behaves. So keep three things in mind:

1. Give a block of code a comment. Whack it on top.
2. You want a newbie to look at your code and go, “I totally get it.”
3. And you want to be able to look back at your own code in 10 years time and think, “Impressive.”

Please avoid:

• Comments that sit beside a line of code. The names of your functions and variables should make it clear what each individual line does. We understand sometimes this is unavoidable, like when dealing with sys ids.
• Commenting on every single line of code. Someone will get slapped. Slap-ees beware.