Re: Using

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.