...more is about to come! As phpWebSite currebtly approaches stable status, a lot of the information herein may be obsoleted. Take the information contained herein with a grain of salt...
Below are some personal comments on the code I found when I joined phpWebSite development. But before you read that, let me introduce you to the preferred coding style.
If you change code and/or write new code you should add appropriate comments. This applies to whole files (so called modules when we talk about procedural code like in phpWS, or classes when talking OO), function/method definitions, included files and important variables.
Always remember: Commenting is important! It helps you to understand other's code faster, makes it easier to understand your own code and is a Good Thing [tm] when it comes to software engineering.
If you used Java, you probably came across javadoc, which generates browseable HTML documentation by extracting specially crafted comments from the sourcecode. There is a similar tool for PHP called (who would have guessed that) PHPDoc. It has been written by Ulf Wendel and may be found in PHP CVS (currently checked in in the PEAR directory) or at http://www.phpdoc.de/. The following is a quick guide to writing the most important types of comments we would like you to use when hacking on phpWebSite..
Aside from module comments (which should come before any code in the file), comments are recognized only if found before a certain keyword. These are:
The available variable types, as far as I know, are:
These should appear at the beginning of every file or right before the class definition, and help to explain the purpose of the file. Further they give the file a name (module) and put the file in a certain group (a module group) if the file does not contain a class definition. If a class is defined in the file, all needed data is derived from the class's name and inheritance. Leave out the module and modulegroup statement in this case! All phpWebSite modules/classes should belong to the package phpWebSite. This might be helpful in the future, if code is distributed with phpWebSite that is not part of the core package (e.g. certain modules). Such a comment looks like this:
/** * Short explanation (1 line!) * * Some more text which explains in more detail * what the file does and who might be interested * in understanding that. * * @version [dollar sign]Id[dollar sign] * @author Name <email address> * @module modulename * @modulegroup group * @package phpWebSite */
These explain in detail what a function does, what parameters it expects and what is returned by the function. Function comments apply to classes as well, here they magically turn into method comments. Such a comment appears directly above a function definition looks like this:
/** * Short explanation (1 line!) * * Some more text which explains in more detail what * the function does and who might be interested * in understanding that. * * @author Name <email address>, Name2 <other email address> * @param type description * @return type description */
These are simple: They just quickly explain what a class varibale is used for, or what an included file does, or why we need it. These comments may be longer, if you have to explain more (e.g. the $dbp variable in the config file). They should appear just above the corresponding variable or include/require statement. They have to be one line and look like this. Every included file has to be commented only once in one file, even if used several times.
/** * Some explanation of the variable or file just below this comment. */
Those of you using emacs will notice that c-mode and php-mode know those comments and indent, wrap and colourize them correctly. It might be worth trying to use one of the available javadoc editing tools (I didn't try, but if you do, let me know). You should add a single space character at the end of lines in a multi line comment - otherwise the result might look, uhm, interesting. If something seems odd - DON´T PANIC (42, you remember?). PHPDoc is still a young piece of software, not every error has to be your fault. Finally: I will try to run PHPDoc weekly and put up the results at http://www.k-fish.de/krabutzig/phpwebsite/
Some asked whether comments like the following are possible:
/******************************************************************* * Some explanation of the variable or file just below this comment. ******************************************************************/
This was meant to make the code better to navigate - but alas it does not work. Err... it works, but the results look rather funny, because the leading line of *´s is included in the generated documentation. Similar things happen to the closing line of *´s. So all I can say is: stick with exactly the format shown above. I hope this will someday be resolved in PHPDoc, until then we have to wait.
Feel free to add more comments (preferably c-style, i.e. start them with //, not #) in your code to explain what you are doing. And if you write even more detailed documentation, feel free to link them to these docs and put them in CVS.
And please take a look at the section titled "Report" in the generated API documentation. This way you can spot errors and deficiencies in the documentation and fix them.
/* index.php */
include open_session.php
include mainfile.php
include config.php
set $index=1
set $storynum to either $cookie[3] or $top
include header.php
/* header.php */
include config.php
CacheControl()
DOCTYPE xhtml DTD
if banners {include banners.php}
function head()
include config.php
global variables
if unique titles {$titelag=menu_text}
if user {
include $theme/theme.php
/* $theme/theme.php */
/* end $theme/theme.php */
include $theme/header.php
/* $theme/header.php */
<head>
<title> $sitename - if {$titletag}
<link> to css stylesheet
<meta>
</head>
<body>
<table> for website boundaries
<table> inner 3 column table for page layout
display logo and search form
display $titlebar (slogan)
<table> for menu
include menu.php
display $AdminBlock if $admintest true using themesidebox
plug_check(1,0,NULL,NULL)
display User Login Block if {} using themesidebox
mysql_query SELECT leftblocks
create array of leftblocks from query
display array of leftblocks using themesidebox
/* end $theme/header.php */
}
head()
include counter.php
/* end header.php */
call plug_check(2,0,NULL,NULL)
mysql_query SELECT articles limit $storynum
mysql_query SELCECT main_page_content
show main content using thememainbox
show articles using themeindex
include footer.php
/* footer.php */
function foot()
include config.php
global variables
if user {
include $theme/footer.php
/* $theme/footer.php */
include config.php
display poll if $active true
display user block if $cookie[8] true
plug_check(3,1,flag_begin,col_begin)
mysql_query SELECT rightblocks
create array of rightblocks from query
display array of rightblocks using themesidebox
mysql_query SELECT articles limit $storynum, $oldnum
display past articles using themesidebox
</table>
</table>
/* end $theme/footer.php */
}
// use of the style avoid IE5.5 and 6 problems */
<div class=smalltextatbottom style="text-align : center">
result = mysql_query SELECT footlines from flags
list(footlines) = mysql_fetch_row(result)
footlines
</div>
</body>
</html>
foot()
/* end footer.php */
get http referrer
/* end index.php */
Many thanks to Eric T. Wallace for updating this for version 0.8.0!
| $menu is | function |
|---|---|
| <100 | menu1() |
| <10000 | menu2() |
| <1000000 | menu3() |
If you look at the themes provided, it is not instantly clear what these files do exactly, and where the functions used within are defined. This doesn´t get better if you discover that some of them are redeclared throughout the files! This will be addressed with a theme API. Keep this in mind when reading the following, it is mostly meant to aid in developing a better scheme.
A (standard) theme currently consists of four PHP files, a CSS file and one image file.
phpWebSite always prepends a XHTML header, as required by the standards. So you must start with the <head> tag and omit the <body> tag! And it always appends the text contained in $foot1, $foot2, $foot3 to the page and closes the page by appending the closing </body> and </html> tags, so you must omit them as well.