Posted by Jochem Maas on 02/09/05 12:10

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.
>

[Back to original message]