DevFi

Hey, look, another episode!

This time around I’m talking smack about comments. To go with this episode, take a look at this article by Mark Easterbrook.

During the podcast I give a few tips for writing better in-line comments. The most common reason used to justify in-line comments is to document complex code. Here are some tips for writing better code, so it doesn’t need comments:

• Ask a coworker or a friend for help
• Use Google Code Search to find similar implementations
• Write out the algorithm using pseudo-code
• Write a test as a way to become a user of your code
• Talk it out with a non-technical person

I also talk about block-level comments, those are the comments you put before a function for API documentation. Here are some tips to keep them in good shape:

• Don’t write them if you don’t have to (e.g. private methods)
• Don’t go into unnecessary detail
• Try to make them invariable
• After changing code, read the comments and make sure they match

Files for this show:

• AAC
• MP3

Feedback:

Please leave a comment, or send us an email. Motivate us to do more shows!