Comments on: Where Comments Are Useful http://www.brandonsavage.net/where-comments-are-useful/ The personal blog of Brandon Savage. Contains entries of a personal and professional nature focusing on PHP, Apple, LAMP, MySQL and Washington, DC. Thu, 18 Mar 2010 20:17:39 +0000 http://wordpress.org/?v=2.9.2 hourly 1 By: Joe Leblanc http://www.brandonsavage.net/where-comments-are-useful/#comment-374 Joe Leblanc Fri, 26 Dec 2008 22:06:05 +0000 http://dev.brandonsavage.net/?p=107#comment-374 I think that one of these days, I'm going to get a bumper sticker reading "not all code is poetry." Self-descriptive code can help to a point, but if you're doing client driven work, you're eventually going to have to write something that works regardless of how it reads in the code. This is where comments are vital: when you have to describe a process that is not immediately obvious. I also agree with Eli's "write out the process step-by-step" advice. When you do this, you frequently find opportunities to create functions and classes to separate out your logic. Writing documentation has also helped me find bugs in functions (oh, I thought I was returning an array, etc...) I think that one of these days, I’m going to get a bumper sticker reading “not all code is poetry.” Self-descriptive code can help to a point, but if you’re doing client driven work, you’re eventually going to have to write something that works regardless of how it reads in the code. This is where comments are vital: when you have to describe a process that is not immediately obvious.

I also agree with Eli’s “write out the process step-by-step” advice. When you do this, you frequently find opportunities to create functions and classes to separate out your logic. Writing documentation has also helped me find bugs in functions (oh, I thought I was returning an array, etc…)

]]>