hey rob.. like i said.. hadn't followed the thread... and yes, i too would say commenting every 2-3 lines is pretty much a waste.. for production code, my rule of thumb, and something i've 'encouraged' people working for me, was/is ~100 lines of code (max) for a routine... this varies, but it's about what you can easily read up/down in an editor on a screen, without having to scan back/forth.. but i also encourage developers who are implementing any serious algorithms/calculations to damn sure insert their assumptions, or to point to external docs that explain things in more specific detail. just part of the working product. peace... -----Original Message----- From: Robert Cummings [mailto:robert@xxxxxxxxxxxxx] Sent: Sunday, January 14, 2007 11:45 AM To: bedouglas@xxxxxxxxxxxxx Cc: 'Brian P. Giroux'; php-general@xxxxxxxxxxxxx Subject: RE: Normalized Numbers On Sun, 2007-01-14 at 11:21 -0800, bruce wrote: > hi... > > haven't followed the entire thread.. just saw this portion that pertains to > comments.... > > i can only assume you guys are relatively young.. if you ever have to pick > up a piece of code that was developed 10 years ago, and you need to track > down/test/get back into production in a matter of a few days, then you had > better pray that the code was either 1) carefully used the variable > declarations in a matter that you understand, or 2) that the code has > copious comments at both the functional level as well as the line/section > level, and that the routines discussed the functions that use the routine, > as well as where the inputs are coming from, and going to... > > there's a huge difference in dealing with something that runs a small > website, and something that controls a processing line, where if you screw > it up, you're going to cost $5K/hour when the code is screwing up!!!! > > my $0.02 worth.... > > ps. keep in mind, one person's clear code declarations can be complete > garbage to another person, and you forget why in the hell you did something > over time... clear code comments are a way to (hopefully) make sense of what > the overall chunk of code is supposed to accomplish!! Nobody disagrees with clarifying unclear or ambiguous code. But we do think it's unnecessary for every single line of obvious code to be documented. The time it takes to get up to speed in any source code depends on the quality of the comments, not the quantity. If every single lines has a comment of the types, /* here we enter the blah loop /*, /* here we increment the oogley boogley */, /* end of while loop */, you can be quite sure this amount of copious ridiculous commenting will increase the noise level and make it difficult to see what is important. We all know what ++ does, we know what strlen() does, we generally know what most system functions do. If you have too much noise in the comments, the reader 5 years down the road is going to miss important comments because after reading 5 to 10 frivolous comments they are going to start scanning instead of reading. Cheers, Rob. -- .------------------------------------------------------------. | InterJinn Application Framework - http://www.interjinn.com | :------------------------------------------------------------: | An application and templating framework for PHP. Boasting | | a powerful, scalable system for accessing system services | | such as forms, properties, sessions, and caches. InterJinn | | also provides an extremely flexible architecture for | | creating re-usable components quickly and easily. | `------------------------------------------------------------' -- PHP General Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php -- PHP General Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
