Re: [PHP-DOC] MySQL examples need review

[Gabor Hojtsy]

 I was just updating polish mysql.xml, and I must say that original version
 is a real mess when it comes to examples. There are lot of different
naming
 and coding conventions. I think this file needs general review of its
 examples.

Yes, we are already in the discussion of coding standards. IMHO
we should agree on a coding standard, and then if you or anybody
have the time, mysql.xml and other inconsistent files can be
corrected... Can you add anything to our coding conventions
discussion?

Goba

Re: [PHP-DOC] MySQL examples need review

[Slawomir Pucia]

 Can you add anything to our coding conventions
 discussion?

First of all, I'm after PEAR coding standard in examples. However, there are
some elements which are not covered by PEAR docs:

1. Always use the same values for server, userneme, password and database
name, when connecting to database.
2. Always use or die(...) in database examples.
3. Use print 'foo' when foo doesn't need to be parsed.
4. Use lowercase in HTML tags.
5. Don't use $query='...'; mysql_query($query) when its not needed.
6. Don't use a variable which in not set in example (see $user in
mysql_field_name example).
7. Decide whether to use echo or print (and printf) for output. I preffer
echo.


slawek-

Re: [PHP-DOC] MySQL examples need review

[Egon Schmid]

From: Slawomir Pucia [EMAIL PROTECTED]

  Can you add anything to our coding conventions
  discussion?

 First of all, I'm after PEAR coding standard in examples. However,
there are
 some elements which are not covered by PEAR docs:

First of all you should know, that the first writting of PHPDOC was
only a rewrite of Rasmus PHP/FI manual. More and more authors and
contributors asked many times for a coding standard. So there we
included some in the source. After PEAR was born, Stig or other
persons wrote another for PEAR. Both standards differ in many
places. So I argue to stay with the current coding standards and
improve that.

 1. Always use the same values for server, userneme, password and
database
 name, when connecting to database.

The database marliesle was very helpful to detect plagiarism.

 2. Always use or die(...) in database examples.
 3. Use print 'foo' when foo doesn't need to be parsed.
 4. Use lowercase in HTML tags.
 5. Don't use $query='...'; mysql_query($query) when its not
needed.
 6. Don't use a variable which in not set in example (see $user in
 mysql_field_name example).
 7. Decide whether to use echo or print (and printf) for output. I
preffer
 echo.

-Egon

Re: [PHP-DOC] MySQL examples need review

[Gabor Hojtsy]

 First of all you should know, that the first writting of PHPDOC was
 only a rewrite of Rasmus PHP/FI manual. More and more authors and
 contributors asked many times for a coding standard. So there we
 included some in the source.

Some things were covered in the old howto (for those who
can't remember, see the history of howto.xml in the root of
phpdoc). These were mainly function naming standards,
that are part of the php-dev work standards, and not phpdoc
conventions. The only rule stayed is the use 4 spaces rule.
Where can we find other standards developed in the
past for phpdoc?

 After PEAR was born, Stig or other persons wrote another
 for PEAR. Both standards differ in many places. So I argue
 to stay with the current coding standards and improve that.

OK, if you can show a written down standard somewhere,
even if it was somewhere there in the history,  but now not
active, we can start off from that...

Goba

Re: [PHP-DOC] MySQL examples need review

[Egon Schmid]

www.concertband.de

  First of all you should know, that the first writting of PHPDOC
was
  only a rewrite of Rasmus PHP/FI manual. More and more authors
and
  contributors asked many times for a coding standard. So there we
  included some in the source.

 Some things were covered in the old howto (for those who
 can't remember, see the history of howto.xml in the root of
 phpdoc). These were mainly function naming standards,
 that are part of the php-dev work standards, and not phpdoc
 conventions. The only rule stayed is the use 4 spaces rule.
 Where can we find other standards developed in the
 past for phpdoc?

See version 1.1 of README. The latest version have now only a link
to the howto.tar file.

  After PEAR was born, Stig or other persons wrote another
  for PEAR. Both standards differ in many places. So I argue
  to stay with the current coding standards and improve that.

 OK, if you can show a written down standard somewhere,
 even if it was somewhere there in the history,  but now not
 active, we can start off from that...

Go ahead :)

-Egon

Re: [PHP-DOC] MySQL examples need review

[Gabor Hojtsy]

 See version 1.1 of README. The latest version have now only a link
 to the howto.tar file.

OK, I have seen that file now.
http://cvs.php.net/co.php/phpdoc/README?r=1.1

Look at the function skeleton for example in that file:

function some_code($foo)
{
/* we all agree that four spaces of indentation is good? */
}

isn't that similar to PEAR standards?

This file is not that much different than the current howto
contents about conventions. This 1.1 really have no coding
conventions, just some skeletons. No rules about how to write
PHP code, except the ?php ? form convention in point 5.

So where we can find the previously written down
conventions used for writing PHP code in phpdoc?
This file is even not consistent with what you
have said about before-PEAR coding standards, as
I can see.

Goba

Re: [PHP-DOC] MySQL examples need review

[Egon Schmid]

From: Gabor Hojtsy [EMAIL PROTECTED]

  See version 1.1 of README. The latest version have now only a
link
  to the howto.tar file.

 OK, I have seen that file now.
 http://cvs.php.net/co.php/phpdoc/README?r=1.1

 Look at the function skeleton for example in that file:

 function some_code($foo)
 {
 /* we all agree that four spaces of indentation is good? */
 }

 isn't that similar to PEAR standards?

Sure, I have only forgotten to change.

 This file is not that much different than the current howto
 contents about conventions. This 1.1 really have no coding
 conventions, just some skeletons. No rules about how to write
 PHP code, except the ?php ? form convention in point 5.

 So where we can find the previously written down
 conventions used for writing PHP code in phpdoc?
 This file is even not consistent with what you
 have said about before-PEAR coding standards, as
 I can see.

I have done much formatting without reading the README. I hoped if
peoble read diffs, there would a common census about the rules. The
old history has gone, the project started in 1997. At the beginning
there have been only a few people who where able to validate and
build the manual. So I formatted it myself.

-Egon

Re: [PHP-DOC] MySQL examples need review

[Gabor Hojtsy]

  This file is not that much different than the current howto
  contents about conventions. This 1.1 really have no coding
  conventions, just some skeletons. No rules about how to write
  PHP code, except the ?php ? form convention in point 5.
 
  So where we can find the previously written down
  conventions used for writing PHP code in phpdoc?
  This file is even not consistent with what you
  have said about before-PEAR coding standards, as
  I can see.
 
 I have done much formatting without reading the README. I hoped if
 peoble read diffs, there would a common census about the rules. The
 old history has gone, the project started in 1997. At the beginning
 there have been only a few people who where able to validate and
 build the manual. So I formatted it myself.

So there is no common standard we can see written down,
and agreed by phpdoc people previously. As you say, you hope
we follow commits, and see the standards used there.
BUT as many people committed many things to the phpdoc files,
we can see no comon standard in files. This started the
discussion about standards. And as there is no common standard
written down, and the things in README 1.1 you referred to as
the old standard so closely resembles PEAR (functions, spaces),
we can start off with that. What do you think about that?

Goba

Re: [PHP-DOC] MySQL examples need review

[Jan Lehnardt]

Hi,
On Sun, 23 Dec 2001 18:38:45 +0100
Gabor Hojtsy [EMAIL PROTECTED] wrote:

 What do others think about that?
I give a +1 for adapting the PEAR coding standard for Manual examples.
Some things must be recognized. At first PEAR does have a excellent
error handling, but it is to complex to intoduce it inside of examples
in the PHP manual. Nevertheless error handling is needed. I vote for the
'or die()' construct where needed (e.g. mysql_connect() and friends). As
Slawomir Pucia said some mails ago, we should be consistent about using
' or  for strings (+1 for ' where no metachars or variables need to be
parsed). $variables shoud be concatenated with '. instead of using $var
strng. Lowercase html-tags. Don't use $query='...';
mysql_query($query) when its not needed. Be consistent with echo or
print(f) (+1 for echo).


 Merry Christmas and a Happy new year to you Egon, and
 to everybody reading these mails. :)
the same to you. 

Jan
-- 
Q: Thank Jan? A: http://geschenke.an.dasmoped.net/

Re: [PHP-DOC] MySQL examples need review

[Slawomir Pucia]

 $variables shoud be concatenated with '. instead of using $var strng.

What is the reason? If there aren't any efficiency considerations then IMHO
$var strng is more clear.

slawek-

Re: [PHP-DOC] MySQL examples need review

[James Moore]

  What do others think about that?
 I give a +1 for adapting the PEAR coding standard for Manual examples.

-1 for anything complicated in the manual. Keep everything clear and concise
why do we need to clutter examples with PEAR error everywhere (Nothing
against pear I think its great but I dont think its all that clear for
examples in a manual.) Most code out there isnt written with PEAR at all and
thus when comparing code and the manual it might be unclear to the reader.

- James

Re: [PHP-DOC] MySQL examples need review

[Slawomir Pucia]

 -1 for anything complicated in the manual. Keep everything clear and
concise
 why do we need to clutter examples with PEAR error everywhere

AFAIK the idea is to adapt PEAR *coding standard* to examples, not to use
PEAR itself.

slawek-

Re: [PHP-DOC] MySQL examples need review

[Philip Olson]

I don't think anyone means 'use pear' in the examples, just the standard.
Like, what makes for a defining a function, construct spacing, etc.  Odds
are the pear coding standard will be a base which will be modified to suit
phpdoc needs.

Regarding whether to use echo or print, concat variables or not, etc.  No
need to get that specific imho.  Just the basics, like formatting.

And fwiw, I'm against forcing 'or die' formatting in any example, it's not
all that flexible.

Regards,
Philip Olson




On Sun, 23 Dec 2001, James Moore wrote:

 
 
   What do others think about that?
  I give a +1 for adapting the PEAR coding standard for Manual examples.
 
 -1 for anything complicated in the manual. Keep everything clear and concise
 why do we need to clutter examples with PEAR error everywhere (Nothing
 against pear I think its great but I dont think its all that clear for
 examples in a manual.) Most code out there isnt written with PEAR at all and
 thus when comparing code and the manual it might be unclear to the reader.
 
 - James
 

Re: [PHP-DOC] MySQL examples need review

[Jan Lehnardt]

Hi,
On Sun, 23 Dec 2001 19:37:02 +0100
Slawomir Pucia [EMAIL PROTECTED] wrote:

  $variables shoud be concatenated with '. instead of using $var
strng.
 
 What is the reason? If there aren't any efficiency considerations then
IMHO
 $var strng is more clean 
personal opinion, I think $var.'string' is clearer, as some might say
it is less readable and more typing. Feel free to vote against it ;).

Jan
-- 
Q: Thank Jan? A: http://geschenke.an.dasmoped.net/

Re: [PHP-DOC] MySQL examples need review

[Jan Lehnardt]

Hi,
On Sun, 23 Dec 2001 18:59:52 + (GMT)
Philip Olson [EMAIL PROTECTED] wrote:
 And fwiw, I'm against forcing 'or die' formatting in any example, it's
not
 all that flexible.

can you please give an example where 'or die()' is 'not flexible'.

Jan
-- 
Q: Thank Jan? A: http://geschenke.an.dasmoped.net/

Re: [PHP-DOC] MySQL examples need review

[Slawomir Pucia]

 Regarding whether to use echo or print, concat variables or not, etc.  No
 need to get that specific imho.  Just the basics, like formatting.

It simply looks nicer for reader if all examples (at least in one chapter)
are similar. Look at these lines from mysql.xml:

mysql_connect(mysql_host, mysql_login, mysql_password)
mysql_connect(kraemer, marliesle, secret)
mysql_connect(localhost, username, secret)
mysql_pconnect(kron, jutta, geheim)
mysql_connect('dbhost', 'username', 'password');

I'm sure we can work out a set of standard values for host, username and
password, and use them in mysql.xml or even in other database-related
chapters. Although, it's more than just formatting, but IMHO it can help a
reader.

slawek-

[PHP-DOC] Coding Std. [was: Re: [PHP-DOC] MySQL examples need review]

[Marcin Dbrowski 'DomBal']

Hi there.

I thought I'll start a new topic for this. 
You won't punish me for that? :P

  What do others think about that?
 I give a +1 for adapting the PEAR coding standard for Manual examples.
+1 from me.

 Slawomir Pucia said some mails ago, we should be consistent about using
 ' or  for strings (+1 for ' where no metachars or variables need to be
 parsed).
+1

 $variables shoud be concatenated with '. instead of using $var strng. 
-1. I prefer $var string.

 Lowercase html-tags.
+1

 (+1 for echo).
+1

  Merry Christmas and a Happy new year to you Egon, and
  to everybody reading these mails. :)
 the same to you.
+10 :)))
Merry Christmas and a Happy New Year to everyone :).

-- 
`--:[ Marcin ``DomBal'' Dbrowski ]-[ http://dombal.underground.pl/ ]:--.
.--:[ CONTACTmail: [EMAIL PROTECTED] ]-+-[ orgz: CUD, ISOC, PJWSTK, RWO ]:--'
`--:[ ,, Love is the law. Love under will. '' --- (Alister Crowley) ]:--.
.--:[ pgp/gpg fp: 23B8 EBF7 AA65 4F67 B963 3D93 4A5A 5320 422F D293 ]:--'

Re: [PHP-DOC] Coding Std. [was: Re: [PHP-DOC] MySQL examples need review]

[James Moore]

  $variables shoud be concatenated with '. instead of using $var strng.
 -1. I prefer $var string.

$var. string is less ambigious. Actually it should be $var.' string' as
$var string and '$var string' behave differently $var.' string' and $var.
string work the same.

- James

Re: [PHP-DOC] MySQL examples need review

[Philip Olson]

 can you please give an example where 'or die()' is 'not flexible'.

I am referring to 'or' specifically.  For example:

$conn = mysql_connect($host, $user, $pass) or die('Connection failed');

Okay that works.  But let's say one wants to do multiple statements on
failure, the following will not work:

$conn = mysql_connect($host, $user, $pass) or {
  doSomething();
  die('Connection failed');
}

So later down the road when Sammy wants to doSomething() he'll need to
alter the whole statement.  Instead, here's another way:

if (!$conn = mysql_connect($host, $user, $pass)) {
doSomething();
echo 'print stuff';
exit;
}

Or if (!$conn)...  That is why I disagree with 'or' being a 'standard'
here.  Are there ways around it?  Yes.  Is the above just an example?  
Yep.  IMHO :)

Regards,
Philip Olson

Re: [PHP-DOC] MySQL examples need review

[Philip Olson]

Not sure if I agree they need to be identical, I did last month but now it
doesn't seem like a big deal (pending discussion).  Variety is the spice
of life :)

Regarding below examples, 'single quotes' should be used in every
instance. The spacing looks fine, though.  And, whether or not to define a
link id, like $conn, not sure.  Currently I'm for defining one but am not
concerned.

Regards,
Philip Olson

On Sun, 23 Dec 2001, Slawomir Pucia wrote:

  Regarding whether to use echo or print, concat variables or not, etc.  No
  need to get that specific imho.  Just the basics, like formatting.
 
 It simply looks nicer for reader if all examples (at least in one chapter)
 are similar. Look at these lines from mysql.xml:
 
 mysql_connect(mysql_host, mysql_login, mysql_password)
 mysql_connect(kraemer, marliesle, secret)
 mysql_connect(localhost, username, secret)
 mysql_pconnect(kron, jutta, geheim)
 mysql_connect('dbhost', 'username', 'password');
 
 I'm sure we can work out a set of standard values for host, username and
 password, and use them in mysql.xml or even in other database-related
 chapters. Although, it's more than just formatting, but IMHO it can help a
 reader.
 
 slawek-
 
 
 
 

[PHP-DOC] MySQL examples need review

[Slawomir Pucia]

I was just updating polish mysql.xml, and I must say that original version
is a real mess when it comes to examples. There are lot of different naming
and coding conventions. I think this file needs general review of its
examples.

slawek-

Re: [PHP-DOC] MySQL examples need review

[Philip Olson]

Hi Slawek-

Yes, many agree.  There is a discussion on whether or not to use a coding
standard in php examples and if so what standard to use/define.

See the recent thread on 'doc standards'.

regards,
Philip Olson


On Sat, 22 Dec 2001, Slawomir Pucia wrote:

 I was just updating polish mysql.xml, and I must say that original version
 is a real mess when it comes to examples. There are lot of different naming
 and coding conventions. I think this file needs general review of its
 examples.
 
 slawek-