Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Re: [wiki] Core Function Reference
jm wrote:
Clean up any spacing issues, such as no-space between commas (on some hurried-looking functions such as
getCount())
How about avoiding double quotes (or at the very least not using double quotes unless needed), breaking long function calls on a new parameter instead of in a middle of a parameter and adding whitespace around concatenating dots:
return getThing('select count(*) from ' . safe_pfx_j($table) . 'where ' . $where,
$debug);or:
return getThing('select count(*) from ' . safe_pfx_j($table) .
'where ' . $where,
$debug);and break the line at 78-80 chars if possible.
Not that I like seeing 1000 char lines, but breaking a line just because it exceeds a limit isn’t necessarily a good thing in all situations.
The TXP source code uses tabs, so stick with it, but don’t use tab characters to align things (IIRC, publish.php fails at this).
+1. when coding for TXP I’ve tried to use tabs only for code indentation, to avoid crappy code layout for those that use a different tab width, but there are still lots of places where tabs are used for alignment.
/**
* Returns the number of rows matching a condition.
*
* @param string $table Table name
* @param string $where WHERE clause
* @param bool $debug Print the query
*/
function getCount($table, $where, $debug='')Is it possible to add a blank line between the documentation and the function declaration?
Perhaps more important than the suggested PHPdoc documentation is comments on how the code works, especially in places where you otherwise have to stare at code for a day to understand why it was done in a specific way instead of a seemingly simpler way (which turns out not to work).
Offline
Re: [wiki] Core Function Reference
ruud wrote:
How about avoiding double quotes (or at the very least not using double quotes unless needed), breaking long function calls on a new parameter instead of in a middle of a parameter and adding whitespace around concatenating dots:
Gets my vote. Breaking functions at logical parameter points makes more sense to me too than a hard-coded — arguably arbitrary nowadays — limit.
Perhaps more important than the suggested PHPdoc documentation is comments on how the code works, especially in places where you otherwise have to stare at code for a day to understand why it was done in a specific way instead of a seemingly simpler way (which turns out not to work).
Hehehe, yep. Definitely. I would guess this is where the multiline comment comes in handy so the short description becomes the overview and the optional long description gives programmer notes, if applicable (and if a reason for the particular implementation is known!) :
/**
* Returns the number of rows matching a condition.
*
* Could have been done by using sub-flange algorithmic flotsam, but that would break other functions.
* @see rabbit_hole
*
* @param string $table Table name
* @param string $where WHERE clause
* @param bool $debug Print the query
*/
function getCount($table, $where, $debug='')The @access and internal directives to help make two types of documentation — user and programmer — are overkill here imo. I doubt anybody would learn to use TXP by browsing the function reference, even if it did contain ‘end user’ notes :-)
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Txp Builders – finely-crafted code, design and Txp
Offline
Re: [wiki] Core Function Reference
Bloke wrote:
Hehehe, yep. Definitely. I would guess this is where the multiline comment comes in handy so the short description becomes the overview and the optional long description gives programmer notes, if applicable (and if a reason for the particular implementation is known!) :
No, that’s not what I mean. I was referring to adding inline comments (not PHPdoc comments) to make it easier to understand tricky parts of code for current and future maintainers.
The actual implementation details are not that interesting to end users. A black box with a good description and API is fine for most people. That’s where PHPdoc appears to more useful.
Offline
Re: [wiki] Core Function Reference
ruud wrote:
How about avoiding double quotes (or at the very least not using double quotes unless needed), breaking long function calls on a new parameter instead of in a middle of a parameter and adding whitespace around concatenating dots:
That sounds and looks good.
Is it possible to add a blank line between the documentation and the function declaration?
I don’t think so, but I haven’t tested yet – no working phpdoc or doxygen install on this machine (and it’s been awhile since I’ve run either one).
Perhaps more important than the suggested PHPdoc documentation is comments on how the code works, especially in places where you otherwise have to stare at code for a day to understand why it was done in a specific way instead of a seemingly simpler way (which turns out not to work).
I agree – some inline comments (not phpdoc, just block or single-line) comments would be great.
Bloke wrote:
The @access and internal directives to help make two types of documentation — user and programmer — are overkill here imo. I doubt anybody would learn to use TXP by browsing the function reference, even if it did contain ‘end user’ notes :-)
I think access should be deprecated with PHP 5 anyways now that there are real modifiers. (PHP 4: “See, this variable is prefixed with an underscore, so it’s private. Yeah, you can’t touch that! But please don’t try it.”)…but yeah, we don’t need either access or internal.
Edit: Forgot to respond to Stef.
Last edited by jm (2009-10-20 20:06:00)
Offline