current community

your communities

more stack exchange communities

Stack Exchange
tour help
Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.
up vote 0 down vote favorite

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;
}
share|improve this question
    
I do not believe this is a standard way of commenting. I believe the standard way is more like how javadoc understands comment blocks –  Constantin Oct 7 '14 at 1:33

1 Answer 1

up vote 3 down vote accepted

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.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.