Comments on: Why you really, *really* should document your code properly, inside and out http://www.htmlist.com/development/the-bane-of-documentation/ A Web Development Blog by Synapse Studios Sat, 24 Jul 2010 01:54:58 +0000 hourly 1 http://wordpress.org/?v=3.0 By: Effectize http://www.htmlist.com/development/the-bane-of-documentation/comment-page-1/#comment-172 Effectize Tue, 28 Oct 2008 04:59:22 +0000 http://www.htmlist.com/?p=56#comment-172 <strong>89 Ways for You to Become the Coolest Programmer in the World...</strong> Since there are dozens of posts on becoming a better developer, but no single post with all the advice you need, perhaps, you'll find this short guide useful. 1. Learn the Skills You Need Learn the programming basics "The goal of this guide is to b... 89 Ways for You to Become the Coolest Programmer in the World…

Since there are dozens of posts on becoming a better developer, but no single post with all the advice you need, perhaps, you’ll find this short guide useful.
1. Learn the Skills You Need

Learn the programming basics

“The goal of this guide is to b…

]]> By: Magento eCommerce Review: Platform Perils and Impressions, Three Months In :: HTMList.com http://www.htmlist.com/development/the-bane-of-documentation/comment-page-1/#comment-116 Magento eCommerce Review: Platform Perils and Impressions, Three Months In :: HTMList.com Thu, 31 Jul 2008 07:57:59 +0000 http://www.htmlist.com/?p=56#comment-116 [...] The EAV data model is great. It’s fast and makes sense when you have many, many possible attributes to assign to a specific object. However, trying to make database-level changes to all or a subset of products is quite a pain in the ass. This is not so much a knock on Magento since the model does make sense given the options to add arbitrary attributes and such. I suppose this goes back to Magento’s lack of a well-documented database schema (or decent documentation in general). [...] [...] The EAV data model is great. It’s fast and makes sense when you have many, many possible attributes to assign to a specific object. However, trying to make database-level changes to all or a subset of products is quite a pain in the ass. This is not so much a knock on Magento since the model does make sense given the options to add arbitrary attributes and such. I suppose this goes back to Magento’s lack of a well-documented database schema (or decent documentation in general). [...]

]]> By: You Suck At Programming And I Hate You: Things NEVER To Do In PHP & SQL :: HTMList.com http://www.htmlist.com/development/the-bane-of-documentation/comment-page-1/#comment-100 You Suck At Programming And I Hate You: Things NEVER To Do In PHP & SQL :: HTMList.com Fri, 25 Jul 2008 09:17:25 +0000 http://www.htmlist.com/?p=56#comment-100 [...] Document your code. Do it. I’m serious. Use JavaDoc syntax (for PHPDocumentor) and document the hell out of it. Use comments to identify what things are, and use them to describe what you’re doing in situations where your intent is not exceedingly obvious from the code. Some say that if your code is too complex to be understood by looking at it, then instead of commenting, you should simplify your code. That’s ridiculous and those people deserve to be ridiculed. [They're probably mostly Ruby coders.—Ed] Sometimes things are just complicated, and well written comments describing your intent and providing context and explanation for actions is not only essential for other developers to understand your code, but also to help you understand what you were doing when you come back to a project to make changes. (Many a time, I’ve stared at code I wrote for what seemed like hours, trying to remember what the hell I was thinking. Documentation cures this problem. Most of the time.) [...] [...] Document your code. Do it. I’m serious. Use JavaDoc syntax (for PHPDocumentor) and document the hell out of it. Use comments to identify what things are, and use them to describe what you’re doing in situations where your intent is not exceedingly obvious from the code. Some say that if your code is too complex to be understood by looking at it, then instead of commenting, you should simplify your code. That’s ridiculous and those people deserve to be ridiculed. [They're probably mostly Ruby coders.—Ed] Sometimes things are just complicated, and well written comments describing your intent and providing context and explanation for actions is not only essential for other developers to understand your code, but also to help you understand what you were doing when you come back to a project to make changes. (Many a time, I’ve stared at code I wrote for what seemed like hours, trying to remember what the hell I was thinking. Documentation cures this problem. Most of the time.) [...]

]]> By: Sheri Bigelow http://www.htmlist.com/development/the-bane-of-documentation/comment-page-1/#comment-46 Sheri Bigelow Thu, 10 Jul 2008 17:56:20 +0000 http://www.htmlist.com/?p=56#comment-46 Great article. I have one thing to add. I think the whole process of documenting an app makes you a better programmer. When you can explain it in simple terms to an average programmer, you know that you've got a good handle on the code. And, it's so nice to be able to refer back to well documented code, especially when you need to change something in a hurry later. @Chris Cardinal, I also love the <a href="http://codex.wordpress.org/Main_Page" rel="nofollow">WordPress documentation</a>, and I'm also quite impressed with the <a href="http://www.php.net/manual/en/index.php" rel="nofollow">PHP documentation</a> and the <a href="http://dev.mysql.com/doc/refman/5.1/en/" rel="nofollow">MySQL documentation</a> too. Great article. I have one thing to add. I think the whole process of documenting an app makes you a better programmer. When you can explain it in simple terms to an average programmer, you know that you’ve got a good handle on the code. And, it’s so nice to be able to refer back to well documented code, especially when you need to change something in a hurry later.

@Chris Cardinal, I also love the WordPress documentation, and I’m also quite impressed with the PHP documentation and the MySQL documentation too.

]]> By: Michael Kimsal http://www.htmlist.com/development/the-bane-of-documentation/comment-page-1/#comment-24 Michael Kimsal Sun, 08 Jun 2008 13:54:59 +0000 http://www.htmlist.com/?p=56#comment-24 Good points, and something I've been thinking of writing on for a while too. I do not claim to hold myself up as a paragon of good docs, but, like pornography, I know it when I see it (apologies to Justice Potter Stewart!). Many would say what you're asking for fall outside of 'docs' and in to the realm of 'tutorials'. If someone wants to make that distinction, fine. I would then say projects need good tutorials in addition to (or even in place of!) inline javadoc-style comments. Good points, and something I’ve been thinking of writing on for a while too. I do not claim to hold myself up as a paragon of good docs, but, like pornography, I know it when I see it (apologies to Justice Potter Stewart!). Many would say what you’re asking for fall outside of ‘docs’ and in to the realm of ‘tutorials’. If someone wants to make that distinction, fine. I would then say projects need good tutorials in addition to (or even in place of!) inline javadoc-style comments.

]]> By: Chris Cardinal http://www.htmlist.com/development/the-bane-of-documentation/comment-page-1/#comment-19 Chris Cardinal Tue, 03 Jun 2008 09:48:05 +0000 http://www.htmlist.com/?p=56#comment-19 For what it's worth, <a href="http://codex.wordpress.org/Main_Page" rel="nofollow">WordPress' Documentation</a> is pretty stellar, despite our problems with the platform. It makes extending through plugins feasible, which is another great reason to document your code and your project's capabilities in full. For what it’s worth, WordPress’ Documentation is pretty stellar, despite our problems with the platform. It makes extending through plugins feasible, which is another great reason to document your code and your project’s capabilities in full.

]]>