Active
Project:
Coding Standards
Component:
Coding Standards
Priority:
Normal
Category:
Feature request
Assigned:
Unassigned
Reporter:
Created:
27 Nov 2010 at 23:39 UTC
Updated:
21 Nov 2022 at 09:35 UTC
Jump to comment: Most recent
It is often unclear which functions in Drupal core and contrib modules can be relied upon to be API stable.
Some functions are prefixed with _ to indicate they are private.
Most functions are not intended to be API functions and should not be relied upon as they may change.
Functions that are intended to be API functions should be marked with @public - this is a standard Doxygen command: http://www.stack.nl/~dimitri/doxygen/commands.html#cmdpublic
Functions not marked with @public (the majority) should be presumed to be private and should not be called from outside core / their module.
It would not be necessary for private functions to have a _ .
api.drupal.org could be updated to highlight which functions are API functions.
Obviously functions in classes would not need to have this.
Example:
/**
* Return nodes attached to a term across all field instances.
*
* This function requires taxonomy module to be maintaining its own tables,
* and will return an empty array if it is not. If using other field storage
* methods alternatives methods for listing terms will need to be used.
*
* @public
*
* @param $tid
* The term ID.
* @param $pager
* Boolean to indicate whether a pager should be used.
* @param $limit
* Integer. The maximum number of nodes to find.
* Set to FALSE for no limit.
* @order
* An array of fields and directions.
*
* @return
* An array of nids matching the query.
*/
function taxonomy_select_nodes($tid, $pager = TRUE, $limit = FALSE, $order = array('t.sticky' => 'DESC', 't.created' => 'DESC')) {
Comments
Comment #1
j.somers commentedI personally am all in favor of adding extra documentation tags which serve a generic purpose.
On the other hand, I rarely read the documentation that's located above a function so removing the "_" is not something I'd like to see. Whenever I want to find out what a function does or how it works I'd rather look at the actual code because I learned (mostly from other projects, Drupal is actually quite good) the function documentation is mostly outdated or doesn't cover everything. This means that I would consider every function that's not prefixed with an "_" as public. Whenever I want to call a function the auto complete groups all private functions together and I know that I don't need to call any of those functions, unless I explicitly want to.
The other option is to take this one step further. I remember a discussion with a C# programmer a while ago who argued that there is almost no need into making private functions. His idea was that everything should be written as an API and every function should be public serving a single purpose. That's another direction to which the code base could evolve.
Comment #13
quietone commentedMoving this issue to the Coding Standards queue.