Esiste un particolare standard di codifica con commenti tra nome funzione e corpo?

Question

Esiste un particolare standard di codifica con commenti tra nome funzione e corpo?

#1 da (4 voti)

1

Mi sto integrando con un'API di spedizione integrata in php.

Hanno uno strano standard di codifica in cui i commenti sono tra il nome della funzione e la prima parentesi graffa .. che - soggettivamente - rende il codice veramente difficile da leggere.

Si tratta di uno standard di commento particolare, anche se non standardizzato?

Ecco un esempio di una tale funzione

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

coding-standards comments php

posta Ben 07.10.2014 - 01:10

fonte

1 risposta

Leggi altre domande sui tag coding-standards comments php

Quale convenzione di denominazione dovresti usare per gli oggetti dati destinati esclusivamente ai parametri [chiuso] Costruire l'astrazione dei dati per numeri razionali usando "oggetti"

score 4 · Accepted Answer

Il codice PHP tende a utilizzare un blocco prima della funzione:

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

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

Ho visto molto C, Java, JavaScript, Perl e altro codice che usa uno stile simile a quello precedente. Comunque altri linguaggi (Python mi viene in mente più velocemente) usano questo stile "tra la definizione e il codice". Per esempio:.

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

Esistono numerose altre convenzioni che tendono ad essere specifiche del linguaggio e / o della documentazione per documentare tipi, scopi e valori predefiniti per parametri e tipi di ritorno.

Quindi lo stile è idiosincratico per la comunità PHP, ma non fuori limite considerando tutti gli stili di documentazione comuni.

Ecco altro sullo stile PHP DocBlock .