RE: Normalized Numbers

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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


[Index of Archives]     [PHP Home]     [Apache Users]     [PHP on Windows]     [Kernel Newbies]     [PHP Install]     [PHP Classes]     [Pear]     [Postgresql]     [Postgresql PHP]     [PHP on Windows]     [PHP Database Programming]     [PHP SOAP]

  Powered by Linux