Re: Documentation Preferences: Perl and Php Compared (Was: Text Adventure Resources, PHP4 Criticism)
- From: Veli-Pekka Tätilä <vtatila@xxxxxxxxxxxxxxxxxxxx>
- To: programmingblind@xxxxxxxxxxxxx
- Date: Tue, 18 Sep 2007 00:10:50 +0300
Hi Sina,
Warning: pretty subjective stuff and strong opinions ahead. Your mileage
may vary, and at any rate, it is easy to criticize a design afterwords.
Another point is that PHP and Perl serve different purposes and
different audiences, being better is relative and about the context of
use and kind of users. I hope this discussion will not degenerate into
perl and PHP bashing, rather I hope to here views to why people like
either kind of docs, or something else particularly.
OK, phew, PHP docs were not quite as bad as I recalled. Still looking at
the string functions, for instance, there are basic operations, and then
advanced stuff like Soundex or levenshtein, which would be different
modules in Perl? Why does it make sense to lump alls tring functions
into one big module, might I ask?
Also, many of those could be generalized. I find the rot 13 function
pointless, why not create a rotN function, with a customizable character
set, if we're talking about language libraries and reuse. Rot13 could be
implemented with a single tr statement in Perl, thus it is not a
function I would include in a core datatype like a string.
Where Perl has got one substr function in the core language, PHP has got
at least four. I like the minimalism since that's less to remember.
WOuld be even cooler if splice would replace push, pop, shift, and
unshift, in the name of minimalism. I've found that Perl 5 is actually
already fairly minimalist as far as core math, string, array, hash and
object orientation support goes.
Maybe the fact that I'm not a native English speaker affects matters,
names like unshift are not immediately intuitive to me.
Another bad example is shuffle in the string class. What's the point of
possibly duplicating shuffling code in the string class? It would be far
better if there was a genral mechanism to shuffle lists and strings
could be molded to fit that kind of usage pattern. These are just some
of the examples.
Comparing the docs of Perl and PHP's substr, I find the Perl version
much more concise, easier to read, les distracting as theres les trivial
example code, and sharper on boundary cases. That's not to say there is
no bad Perl documentation, though. Compare:
Quote PHP:
string substr ( string $string, int $start [, int $length] )
Returns the portion of string specified by the start and length
parameters.
string The input string.
start If start is non-negative, the returned string will start at the
start'th position in string, counting from zero. For instance, in the
string 'abcdef', the character at position 0 is 'a', the character at
position 2 is 'c', and so forth.
If start is negative, the returned string will start at the start'th
character from the end of string.
Example 2454. Using a negative start
<?php
$rest = substr("abcdef", -1); // returns "f"
$rest = substr("abcdef", -2); // returns "ef"
$rest = substr("abcdef", -3, 1); // returns "d"
?>
length
If length is given and is positive, the string returned will contain at
most length characters beginning from start (depending on the length of
string). If string is less than or equal to start characters long, FALSE
will be returned.
If length is given and is negative, then that many characters will be
omitted from the end of string (after the start position has been
calculated when a start is negative). If start denotes a position beyond
this truncation, an empty string will be returned.
Example 2455. Using a negative length
<?php
$rest = substr("abcdef", 0, -1); // returns "abcde"
$rest = substr("abcdef", 2, -1); // returns "cde"
$rest = substr("abcdef", 4, -4); // returns ""
$rest = substr("abcdef", -3, -1); // returns "de"
?>
Return Values
Returns the extracted part of string.
End quote.
Quote Perl:
substr EXPR,OFFSET,LENGTH,REPLACEMENT
substr EXPR,OFFSET,LENGTH
substr EXPR,OFFSET
Extracts a substring out of EXPR and returns it. First character is at
offset 0, or whatever you've set $[ to (but don't do that). If OFFSET is
negative (or more precisely, less than $[), starts that far from the end
of the string. If LENGTH is omitted, returns everything to the end of
the string. If LENGTH is negative, leaves that many characters off the
end of the string.
my $s = "The black cat climbed the green tree";
my $color = substr $s, 4, 5; # black
my $middle = substr $s, 4, -11; # black cat climbed the
my $end = substr $s, 14; # climbed the green tree
my $tail = substr $s, -4; # tree
my $z = substr $s, -4, 2; # tr
You can use the substr() function as an lvalue, in which case EXPR must
itself be an lvalue. If you assign something shorter than LENGTH, the
string will shrink, and if you assign something longer than LENGTH, the
string will grow to accommodate it. To keep the string the same length
you may need to pad or chop your value using "sprintf".
If OFFSET and LENGTH specify a substring that is partly outside the
string, only the part within the string is returned. If the substring is
beyond either end of the string, substr() returns the undefined value
and produces a warning. When used as an lvalue, specifying a substring
that is entirely outside the string is a fatal error. Here's an example
showing the behavior for boundary cases:
my $name = 'fred';
substr($name, 4) = 'dy'; # $name is now 'freddy'
my $null = substr $name, 6, 2; # returns '' (no warning)
my $oops = substr $name, 7; # returns undef, with warning
substr($name, 7) = 'gap'; # fatal error
An alternative to using substr() as an lvalue is to specify the
replacement string as the 4th argument. This allows you to replace parts
of the EXPR and return what was there before in one operation, just as
you can with splice().
my $s = "The black cat climbed the green tree";
my $z = substr $s, 14, 7, "jumped from"; # climbed
# $s is now "The black cat jumped from the green tree"
End quote.
Even more to my liking, is the K&R version. Since substr in C is just
strcpyn with some pointer arithmetic to specify an offset, the example
function here is strtok:
Quote K&R:
In the following table, variables s and t are of type char *; cs and ct
are of type const char *; n is of type size_t; and c is an int converted
to char.
<snippage>
char *strtok(s,ct)
strtok searches s for tokens delimited by characters from ct; see
below.
A sequence of calls of strtok(s,ct) splits s into tokens, each delimited
by a character from ct. The first call in a sequence has a non-NULL s,
it finds the first token in s consisting of characters not in ct; it
terminates that by overwriting the next character of s with '\0' and
returns a pointer to the token. Each subsequent call, indicated by a
NULL value of s, returns the next such token, searching from just past
the end of the previous one. strtok returns NULL
when no further token is found. The string ct may be different on each
call.
End quote.
Finally I do realize the preferred style of documentation is a matter of
programming experience, language preferences, culture that goes with a
particular language and the coder's familiarity with the problem domain
the thing being documented is trying to solve. These are just my
preferences for pretty familiar functions, your mileage may vary.
--
With kind regards Veli-Pekka Tätilä (vtatila@xxxxxxxxxxxxxxxxxxxx)
Accessibility, game music, synthesizers and programming:
http://www.student.oulu.fi/~vtatila
Sina Bahram wrote:
>
> Php is rather well documented, and not just in .chm format.
>
> You can go to php.net followed by any name of a function, such as
>
> http://php.net/strlen
>
> Or, if you want a general topic, just type that, like for MySQL:
>
> http://php.net/
>
> I'm sure it would be trivial to integrate this into at least one of what
> seems like the hundreds of text editors that go across this list.
>
> Furthermore, it's incorrect to say a language's documentation is bad when a
> particular editor doesn't happen to support it. Those two statements are
> unrelated, as far as I'm concerned.
>
> Take care,
> Sina
>
> -----Original Message-----
> From: programmingblind-bounce@xxxxxxxxxxxxx
> [mailto:programmingblind-bounce@xxxxxxxxxxxxx] On Behalf Of Octavian Rasnita
> Sent: Monday, September 17, 2007 3:43 PM
> To: programmingblind@xxxxxxxxxxxxx
> Subject: Re: Text Adventure Resources, PHP4 Criticism (Was: Is there a
> program that will let me create text adventures?)
>
> Well, I don't think PHP has a lower security than perl (if the programmer
> knows what he does, of course).
>
> I found that PHP's syntax is very closed to perl's syntax, but it is just
> much less developed than perl's.
>
> For example, you could include an array element or a hash element in a
> quoted string without needing to use additional params for letting the
> language know that it is a separate element that should be replaced with its
> value.
>
> Then in very many fields perl is better not because of the core language,
> but because there are much developed modules. And I am thinking for example
> to the list of frameworks that can be used in perl, the templating systems
> and what they can do, the ORM libraries, and other things. I am also
> thinking that perl can be used to create programs with a graphical interface
> usable on Windows or portable on more operating systems, using Win32::GUI,
> Tk, GTK, WXPerl...
>
> Perl also has disadvantages. For example, the perl programmers tend to not
> care about other languages and the libraries they use if what they do can be
> done better in perl in another way.
> And this is a disadvantage, because some of those libraries could be used
> for interaction between programs made in different languages or platforms.
> Perl can use SOAP, but the XML used by its SOAP is not fully compatible with
> the one used by .net or Java. Most perl programmers don't care about this,
> because they say that there are other protocols of communication much better
> than SOAP, and this might be true, but this is not important if all the
> others got used to use SOAP.
>
> On the other side, PHP copies everything it can from all the languages
> including perl and offer those facilities as built in functions and it tries
> to follow more closely the "fashion" of the web.
>
> PHP is much better than perl for creating small web sites, because it is
> easier to do it in PHP than in perl, however for bigger web sites, that kind
> of web sites that are ran by the system administrator, not on a shared web
> host, perl is better. However, of course, there are much more small web
> sites that just require PHP, Apache and MySQL.
>
> Regarding the documentation, I think PHP has a horrible documentation
> comparing it with perl's one.
>
> If I don't know how to use a certain function or method from a perl module
> or a built in function, I just need to press Control+Shift+E in TextPad,
> type the function or module name and press enter, and the documentation for
> that module or function is printed in a newly created window, and I can read
> it just like any other text.
> And then I can read that is that module used for, which are all the method
> names from it, which are their syntax, but *with examples always* and I can
> even copy and paste some lines of code from there for using them in the
> program.
>
> PHP has a nice CHM and I like that format, but it displays a huge number of
> types of functions, then another huge list of functions for each type, and
> it takes a long time to find what I want even if I search the CHM. But this
> is not the most important thing. What I don't like is the fact that PHP
> doesn't give examples, but gives a technical general example, using for
> example [ and ] for including the optional parameters and it is very hard to
> follow if there are more optional parts and especially in cases when if an
> optional parameter is used, another should be also used...
> Perl's documentation gives an example for each possible situation, showing
> how to access the function without parameters, with only one, with 2, with 3
> and so on, or if there are more, it gives only some examples then describe
> in detail in below.
>
> Perl has a stronger support for Unicode (even some libraries like Win32::GUI
> don't support Unicode at all).
>
> The advantage of PHP is that all the modules are compiled, and the admin
> doesn't need to compile the modules in C on the local machine in order to be
> able to use them, so the admin doesn't need to be the system administrator.
> Well, of course perl can be installed by another simple user than root, then
> compile and install anything he wants, but it is still more complicated to
> do that than just using the language.
> The advantage of perl is that it is more flexible, and if the programmer
> knows what he does, he could install other external libraries and perl
> modules that work with them, and can do much more things than a PHP
> programmer can do with PHP.
>
> So none of them is "better" than the other. Each one is best for some
> things.
>
> Octavian
>
> ----- Original Message -----
> From: "Marlon Brandão de Sousa" <splyt.lists@xxxxxxxxx>
> To: <programmingblind@xxxxxxxxxxxxx>
> Sent: Monday, September 17, 2007 7:25 PM
> Subject: Re: Text Adventure Resources, PHP4 Criticism (Was: Is there a
> program that will let me create text adventures?)
>
> Helo,
> I read this thread now and do understand your points in telling php is a
> little bad thought out. I have to say you that php 5 is better.
> I personally don't like perl sintax style and, if there is a library that
> will require me to turn on safety critical stuff, I won't use them. Although
> I can understand your points, I also agree that I won't use the bad things
> of the language. So I don't think that php is this bad, although it has its
> weaknesses like any other language. I like the php documentation and the way
> php comunities behave when a new programmer needs help.
> Also I found the errors pretty clear to understand and fix.
> Marlon
>
> 2007/9/17, Veli-Pekka Tätilä <vtatila@xxxxxxxxxxxxxxxxxxxx>:
> > Hi alex,
> > For text adventures, there are frameworks, class libraries and parsers
> > that are hard to beat. Inform the bytecode of whose Infocom used in
> > their Zork adventures, among others:
> >
> > http://www.inform-fiction.org/I7/Welcome.html
> >
> > Tads 3 is more object-oriented and advanced:
> >
> > http://www.tads.org/tads3.htm
> >
> > If you don't like writing code some good adventures have also been
> > created using Adrift:
> >
> > http://www.adrift.org.uk/cgi/new/adrift.cgi
> >
> > For what has been done with these tools try:
> >
> > www.ifarchive.org
> >
> > and
> >
> > http://www.sparkynet.com/spag/
> >
> > For quirky game ideas and a whole lot of links go here:
> >
> > http://emshort.wordpress.com/reading-if/
> >
> > I wouldn't necessarily use PHP for Webby adventure development unless
> > you already know that. I've never personally liked the language for
> > many many reasons and writing a parser from scratch is basically
> > wasted effort unless you count learning and the fun of coding
> > something from scratch.
> >
> > Here's what I hate in PHP:
> >
> > * Overly friendly but inexact docs, that is behavior in error
> > conditions not well specified and tone not K&R:ishly formal even if it
> > would be beneficial.
> >
> > * OOP system is very weak in PHP 4, and not extendably minimalist as
> > in Perl 5, for instance.
> >
> > * Only one aggregate data type that blends hash and array access. Hard
> > to tell whether it only contains ints and it seems both the advantages
> > of hashes and arrays are lost. You cannot index non-integer types
> > quite as fast as pointer arithmetic yet the PHP arrays are ordered and
> > hash-like, despite a hashtable being inherently unordered. That's just
> > strange, conceptually, and probably not very efficient.
> >
> > * Syntax is C-like, reference semantics have not been well specified
> > or at least I've never understood them, and the compiler errors often
> > sound like they're straiht from some automatic tools . That is, full
> > of obscure symbols.
> >
> > * Bloated class library at least in php4. There's redundant
> > convenience in places, without the facilities to generalize using
> > callbacks or extra args, and naming is a horible jumble borrowing from
> > which ever language the function in question has been lifted.
> >
> > * PHP doesn't have a good track record in security despite nifty hacks
> > like magic quotes. One bad thing is autovivifying variables based on
> > URl parameters, if I may use the Perl lingo here. That can cause quite
> > bad security issues, if I've understood things correctly, but some PHP
> > libs require that the feature is on.
> >
> > What are the advantages, really, apart from some nifty CGI
> > functionality, and easy initial configuration? It seems to be there's
> > nothing special or really interesting in PHP as a programming language.
> > NOt that such a language could not be nice for Webby stuff given good
> > libs, though.
> >
> > Note that I have only used PHP4 in a project which tried extending the
> > OS Commerce platform for a client's needs. So PHP 5 might be much
> > better and as with Perl, if you are a good coder, you don't do the
> > things that are evil, admitted.
> >
> > Still I thought I'd mention the gripes I have with the lang to
> > generate some discussions for workarounds, clarification and the
> > merits of PHP for new users. Feel free to move this to a separate thread.
> >
> > --
> > With kind regards Veli-Pekka Tätilä (vtatila@xxxxxxxxxxxxxxxxxxxx)
> > Accessibility, game music, synthesizers and programming:
> > http://www.student.oulu.fi/~vtatila
> >
> > alex wrote:
> > > Well i was just wondering if there was a program that will let me
> > > create text adventures? Or is there one for MUDS? (rpgs)?
> > __________
> > View the list's information and change your settings at
> > //www.freelists.org/list/programmingblind
> >
> >
>
> --
> When you say "I wrote a program that crashed Windows," people just stare at
> you blankly and say "Hey, I got those with the system, for free."
> Linus Torvalds
> __________
> View the list's information and change your settings at
> //www.freelists.org/list/programmingblind
>
> __________
> View the list's information and change your settings at
> //www.freelists.org/list/programmingblind
>
> __________
> View the list's information and change your settings at
> //www.freelists.org/list/programmingblind
__________
View the list's information and change your settings at
//www.freelists.org/list/programmingblind
Other related posts:
