Hi,
this one goes out to you Coder!
My wishes for the next year are simple and easy to understand -
PLEASE DOCCUMENT YOUR CODE!
Ask yourself, for who you are coding. You give your sparetime to code
things for PHP, and i think you do this, because you will bring it on.
Do you really think, that extensions that are not documented bring
PHP on the way? How many PHP-Coders do you think will use extensions,
when they maybe not even know that they exists (do not say now "If you
don't know them - you don't need them" please ;)) or at least do not
know HOW to use them because of missing documentation?
I know, that documentation is not the greatest thing on earth to do
for programmers, but it is one of the best things to read for "users".
So please do not blame me and tell me, that it's nice of you to write
the extensions, and we should not force you to document. I will not
listen to that kind of statements. It is nice, yes, but it does not
help PHP, if you do not document it. And i do not think, that every
member of the docu-group is able or willing to understand your whole
code before documenting it. So please help us and make documentation
possible for us.
Rasmus himself states out - AFAIK - that PHP is one of the best
documented Open Source Project. If he is (still) right, you should
really get up and comment your code - so that he stays right.
For a list of missing functions see hartmuts function-table. Well,
it states 89% documented. But this one does not count for example
missing documentation for constants and does not checks the correctness
of the documentation (this can happen, if code is changed but know one
notice this). And - this is even more important - does seem to
count "documentated" functions, that aren't really documented
(i.e. see "dio"-ext, "Mohawk-Software-Session handler functions"-ext.
and so on) and functions, that are not completely documented (i.e. cURL).
Joerg Behrens gave me some ideas, that i will bring to you now. I
think they are really worth thinking about.
(1) Do not accept any new extensions for php-releases, if it's not
documented. fullstop.
(2) Please pay attention if you update/change code that is already
in the repository. Please do not forget to change protos and
to write a line of documentation if necessary.
I do not know, if this makes the world a better place, but maybe it
makes life easier for people using php ...
with best regards,
-Wolfgang
--
Deutscher PHP-Knotenpunkt Dynamic Web Pages: http://www.dynamicwebpages.de
Scripte, Tutorials, Installation, Bücher, BestofGML, Manual, Links uvm.
PHP 4: Dynamische Webauftritte professionell realisieren: http://php-buch.de
--
PHP Development Mailing List <http://www.php.net/>
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
To contact the list administrators, e-mail: [EMAIL PROTECTED]
