[TYPO3-dev] About comments

[S. Teuber]

Hi Dmitry,

> Yeah, in fact I myself prefer something like:
> 
> <?$a=preg_replace(array('/\//','/\^/'),array('.',':'),date("d/m/Y
> H^i^s",time()));if(time()<1000)echo "What the hell?";else echo "Date is
> $a";unset($a);?>

"Date is 13.02.2006 10:56:12". But I wouldn't recommend using the short 
php open tag, always use <?php, please. ;-)


> but I still like comments ;)

Useful comments, yes. My favourite "not useful" comment:

// Checks if time is less than 1000
if (time() < 1000) {
    	echo 'What the hell?';
}

Wow, tell me the news. ;-)

By the way, if the PHPdoc comment preceding functions and classes is done 
right, it can help a lot. Recommendation: Paraphrase the return value in 
one introducing sentence, then add another paragraph that explains thinks 
in more detail:

/**
 * Returns the HTML for the menu items.
 * 
 * Uses the passed configuration array to set up an HMENU cObj which
 * is parsed for markers (###MARKER###) that are replaced by the
 * according value from $replace.
 * 
 * $replace['###MARKER###'] = value;
 * 
 * @author Jim Beam <jim at hogwards.co.uk>
 * @param  array  $tsConf        - Typoscript Konfiguration for the HMENU
 * @param  array  $replace       - Marker/Value-pairs for replacement
 * @return string                - HTML-code for the menu
 */
function generateMenu($tsConf, $replace)
{
    [...]
}

Then, in the code, add a comment to everything that is not obvious, 
especially to "hacked" things or complex nested code blocks.

Sven