Richard Lynch wrote:
Jochem Maas wrote:
Dan Trainor wrote:
Hello, all -
Being still fairly new to PHP, I thought I'd ask a few more questions and get on to the right track here, developing correct coding habits before I start to teah myself incorrect habits.
....
7. let others review your code if you can (that's not an invite to post your complete codebase to the list ;-).
Hmmmmm. It *MIGHT* be an interesting forum somewhere/somehow to have a "Code Review" site/forum/list for the express purpose of people posting code, and tons of it, for critique...
I think such a place would be cool but If you let everyone upload their
code then everyone would be sitting around waiting for their own code to
be reviewed - I think that the reviews should be by invitation
('hey Richard fancy showing the world your new XXX?'),
1 codebase to be reviewed at a time, with a lead reviewer who acts as moderator.
for those of you from the UK... kind of like Blue Peter meets PHP.
I cannot count the number of times I've seen code like this:
/** foo (void) : function foo * Does foo and returns the result **/ function foo(){ /* Insert spaghetti code here */ }
Hello?! What *GOOD* does that "documentation" do?
What always seems to be missing, to me, is the nuts and bolts of how to write GOOD documentation.
I actually meant that you should add comments into the meat of the code. yes,
start of each function with a description. BUT ALSO explain every friggin' loop
so to speak... not just what it does, but how it does it and possibly why.
Richard is correct, I think, in saying that adding fancy Doc cruft to make your
code look 'professional'... nothing wrong with fancy documentation/comments - just
make sure you fill them with something. with the hope of not getting laughed at here
is a function I use quite often to save myself from constant isset() checks on
request vars.
okay so its 'fancy' documentation, but it really explains what it does - and
yes it takes 5-6 times as much text to explain what it does than it does to write
t.
/**
* getGP()
*
* this function will return the value of a GET or POST var that corresponds to the
* variable name pasted, if nothing is found NULL is returned. contents of POST array
* takes precendence over the contents of the GET array. You can specify a value as second argument
* which will be returned if the GP var *does not* exist; a third parameter can be given to
* which will act as the return value if the GP *does* exist - the limitation is that the parameter cannot be
* used to return a literal NULL; but I suggest that this would probably be a silly thing to do in practice
*
* @var string $v // the name of GP variable whose value to return
* @var mixed $r // value to return if the GP variable was not set
* @var mixed $t // value to return if the GP variable was set (i.e. override the value from GP)
*
* @return mixed
*/
function getGP($v = '', $r = null, $t = null)
{
if (!empty($v)) {
if (isset($_GET[$v])) { $r = (!is_null($t)) ? $t: $_GET[$v]; }
if (isset($_POST[$v])) { $r = (!is_null($t)) ? $t: $_POST[$v];}
}
return $r;
}
Anybody got a good reference to something like Documentation Rules such as:
Any jargon or technical term being discussed cannot be used as the description of the term. IE, no self-referential definitions. (see example above)
I'd really like to be able to recommend a reference of this nature to Beginners.
I appreciate all the input that I've gotten from all the list members. I think I've come to the conclusion that leaves me exactly where I was prior to asking the question. The determination to split inline code from included files is left strictly up to the programmer him/herself, and there is no "rule of thumb" to any of this, except in cases where painfully obvious.
I thank you all for your time. I'll continue to monitor this list for many months to come.
Thanks -dan trainor
-- PHP General Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
