1

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;
}
  • 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
4

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.

  • Nitpick: in Python, it's not a coding style, it is part of the language syntax. A lone string literal as the first statement of a declaration is interpreted as an assignment to the instance variable __doc__. – Jörg W Mittag Sep 19 '16 at 20:31
  • Python's official syntax says otherwise. Python 2's syntax, e.g.: funcdef: 'def' NAME parameters ':' suite. Nothing in suite mentions comments. While longer, Python 3's funcdef very similar. It's true most Python implementations recognize and support the convention, but however much PEP 8, PEP 257, and the common idiom encourage it, docstring comments are entirely optional. Tons of Python code ignores the convention, yet runs just fine. – Jonathan Eunice Sep 19 '16 at 21:01
  • It's not a comment. It's a string literal. The special casing is documented in python.org/dev/peps/pep-0257/#what-is-a-docstring – Jörg W Mittag Sep 19 '16 at 21:04
  • Yes, it is a string literal. Your assertion was that it was "part of the language syntax." It's not. The language syntax includes no such thing. PEP 8 and PEP 257 define Python's desired, idiomatic coding style and documentation conventions. Therefore, docstrings are part of Python's style and conventions, not its syntax. – Jonathan Eunice Sep 19 '16 at 21:11
  • I'm not sure what you mean. So you are saying that a docstring is just a string literal like any other? It has no special semantics? But that's not the case: the string literal is not assigned to any variable, not returned, not passed as an argument to any function. It is completely unreferenced. It is created, immediately eligible for garbage collection, and immediately unreachable. An optimizing compiler could even omit it completely. But that is not the case: instead, it is being assigned to an attribute named __doc__, and even represented in the bytecode. Other string literals don't … – Jörg W Mittag Sep 19 '16 at 21:18

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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