|
|
Posted by Dan Trainor on 02/09/05 12:26
Jochem Maas wrote:
> 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
Navigation:
[Reply to this message]
|