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!

So, this time, Chris is the slacker. But here’s the newest episode just a week late. Chris puts forth the importance of reading other people’s code, and has suggestions of where to start if you don’t know where to go.

Next week, Peter will release his episode on time… Probably.

Please post any comments or suggestions right here on this blog.

Files:

• AAC
• MP3