Re: [PHP-DOC] Coding Std. [was: Re: [PHP-DOC] MySQL examples need review]
Hi,
On Sun, 23 Dec 2001 20:36:07 + (GMT)
Philip Olson <[EMAIL PROTECTED]> wrote:
> "a $arr[foo] b"
> "a {$arr['foo']} b"
> 'a ' . $arr['foo'] . ' b';
The first ist simply wrong. with $array[foo] PHP assumes foo is an
constant with the value foo, which is not coorect when using 'strings'
as indices.
Jan
--
Q: Thank Jan? A: http://geschenke.an.dasmoped.net/
Re: [PHP-DOC] MySQL examples need review
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-
>
>
>
>
Re: [PHP-DOC] MySQL examples need review
> 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] Coding Std. [was: Re: [PHP-DOC] MySQL examples need review]
> > $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
[PHP-DOC] Coding Std. [was: Re: [PHP-DOC] MySQL examples need review]
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 -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'' Dąbrowski ]-[ 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] MySQL examples need review
> 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-
Re: [PHP-DOC] MySQL examples need review
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
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
Hi, On Sun, 23 Dec 2001 18:43:50 - "James Moore" <[EMAIL PROTECTED]> 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. to quote myself: " 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)" I said nothing about using PEAR itself in the manual examples. I am against it either. I just want to adapt the PEAR coding standart to the manual. Jan -- Q: Thank Jan? A: http://geschenke.an.dasmoped.net/
Re: [PHP-DOC] MySQL examples need review
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
> -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
> > 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
> $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
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 -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
> Diffs are hard to read. This was a bad example from me. A better one > would be cvs.php.net or the PHP manual itself. But the codes in the manual are so different, as many people added code, without following any convention, so I cannot agree that reading the manual is a good example to get a sense of what standard is used there. In fact we started this discussion, because example codes and outputs differ so much in different places. > Personaly I prefer common standard, but I can also live > with both standards. I would be happy to see that standard written down, you say the PHP Manual is used to conform to, but as there is no such written down standard anywhere, IMHO we can start off to design our own standard based on the few code writing related conventions used now, and the PEAR standard, as a widely known coding standard. And yes, we need to develop our own standards, even if it is based on the PEAR coding standards, because we need some more conventions, such as example writing. What do others think about that? I think we'd better wait till the end of the Christmas and New Year period, so people come back and can reply to this mail with some added opinions... Starting to develop a standard for two or three people currently here would be pointless... Merry Christmas and a Happy new year to you Egon, and to everybody reading these mails. :) Goba
Re: [PHP-DOC] MySQL examples need review
From: "Gabor Hojtsy" <[EMAIL PROTECTED]> > > > 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? Diffs are hard to read. This was a bad example from me. A better one would be cvs.php.net or the PHP manual itself. Personaly I prefer common standard, but I can also live with both standards. -Egon
Re: [PHP-DOC] MySQL examples need review
> > 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 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
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 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
> 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 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
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
> 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
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
> 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
> 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
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- > > > >
