Is there a particular coding standard with comments between function name and body?

Question

I'm integrating with a shipping API built in php.

They have a strange coding standard where the comments are between the function name and the first curly bracket.. which - subjectively - makes the code really hard to read.

Is this a particular, albeit non-standard, commenting standard?

Here's an example of a such a function

public function qualityControlDescription($qcCode)
/*
Converts a Quality Control code (e.g. 'U') to a descriptive string.
Input parameters (case-insensitive):
    $qcCode = a Quality Control code, as returned by invokeWebService

Returned:
    Description string (e.g. 'UNSERVICEABLE'), or "" if not found
*/
{
    if (is_null($qcCode))
    {
        return "";
    }
    $descriptionMap = $this->qualityControlDescriptionMap();
    $returnVal = $descriptionMap[strtoupper($qcCode)];
    if (is_null($returnVal))
    {
        $returnVal = "";
    }
    return $returnVal;
}

Answer 1

PHP code tends to use a block before the function:

/**
 * Is the given array an associative array?
 */

function isAssoc($arr) {
    return array_keys($arr) !== range(0, count($arr) - 1);
}

I have seen much C, Java, JavaScript, Perl, and other code that uses a similar block-before-function style. However other languages (Python comes to mind most quickly) do use this "between the definition and the code" style. E.g.:

def is_string(s):
    """
    Is the given value `s` a string type?
    """
    return isinstance(s, (str, unicode))

There are a number of other conventions that tend to be language- and/or documentation-system specific for documenting the types, purposes, and default values for parameters and return types.

So that style is idiosyncratic for the PHP community, but not out of bounds considering all common documentation styles.

Here is more on the PHP DocBlock style.