Cosa ne pensi dell'apertura di commenti di parentesi nel codice sorgente? [chiuso]

Non consiglierei questo stile in quanto rende difficile la scansione delle parentesi graffe.

void DoSomeInterestingImageManipulation(char *pImage)
{//This will convert the image to formatABC which allows x% space savings for storage
    if(pImage && pImage[0] == 0xFF)
    {//Process the extra case where image internal format needs decompression
        ++pImage;
        //...
        //...
        //...
    }

    //Proceed normally
    *pResult = Foo(pImage);
}

Guarda le parentesi graffe e dimmi dove inizia il blocco.
Ora fai lo stesso per questo:

void DoSomeInterestingImageManipulation(char *pImage)
{
    //This will convert the image to formatABC which allows x% space savings for storage
    if(pImage && pImage[0] == 0xFF)
    {
        //Process the extra case where image internal format needs decompression
        ++pImage;
        //...
        //...
        //...
    }

    //Proceed normally
    *pResult = Foo(pImage);
}

Puoi dirmi dove iniziare più facilmente?

Sembra strano Non c'è nessun problema con esso. Puoi anche fare:

void foobar() {
    // comment explaining function
    ...
}

E ottieni lo stesso numero di linee semplicemente mettendo la parentesi aperta sulla stessa riga del nome della funzione.

Personalmente, non ho mai visto molto in "salvare spazio verticale" fine a se stesso. Abbiamo un sacco di spazio verticale. Ci sono applicazioni là fuori che usano milioni di linee di spazio verticale.

Se qualche metodo diventa troppo grande verticalmente, significa che dovrebbe essere diviso. Mettere sempre più cose nelle stesse linee non è una soluzione, è solo nascondere il problema. A mio avviso, la leggibilità dello stile suggerito è scarsa.

Invece di:

if(pImage && pImage[0] == 0xFF)
{//Process the extra case where image internal format needs decompression
    ++pImage;
    //...
    //...
    //...
}

Just:

if(pImage && pImage[0] == 0xFF)
{
    processDecompressableImage(pImage); // separate method. self-documenting.
}

Penso sia leggibile ma strano. Ogni volta che vedo qualcosa accanto a una coppia, mi aspetto che faccia parte del corpo. Ora un // o un /* lascia il commento lontano, ma non si sente naturale .

Un altro grosso problema è il debug inefficace. Considera questo:

// code

for () { /* comment
    end comment */
loop
} */

//code 

Se decidi di voler commentare il ciclo per testare l'effetto, ciò che finirai per fare è questo:

/* for () { /* comment
        end comment */
    loop
    } */

e il ciclo rimane. Questo è uno strano esempio, ma il problema è lì.

Inoltre, non hai stabilito un motivo concreto per i vantaggi di questo stile. Non credo che contenga "salvare una linea".

Personalmente, non trovo il tuo stile di commento leggibile. Preferisco i miei commenti che spiegano che un blocco di codice è al di sopra del blocco di codice. Nelle lingue che utilizzano parentesi graffe, questo è in genere sopra la parentesi graffa.

Inoltre, ho notato dai tuoi commenti che stai spiegando un sacco di "cosa", anche se questo potrebbe essere solo nell'esempio. Questo in genere diventa obsoleto più velocemente del codice poiché le persone modificano il codice ma non i commenti. Il tuo commento sul fare qualcosa perché fa risparmiare spazio è un buon commento, ma gli altri, non così utili. Non avere i commenti dove non spiegano le motivazioni farebbe risparmiare spazio e migliorerebbe la leggibilità.

Non ho mai visto un pezzo di codice così illeggibile.

Tutti i commenti tra le righe di codice saranno d'intralcio. Devi scrivere il codice auto-documentato e forse considerare un commento prima della funzione.

Quindi, se hai davvero bisogno di avere commenti tra le code line, almeno scriverli prima di un pezzo di codice importante (o non così facile da capire), in una riga vuota e con lo stesso padding del codice qui sotto .

Modifica

Per chiarire, anche con la sintassi che evidenzia i commenti sembra fuori luogo rispetto al codice stesso, a causa di padding mancanti.

Per una migliore leggibilità, i paddings e le linee vuote sono ottimi per separare diverse porzioni di codice. Insieme all'evidenziazione della sintassi, ottieni una maggiore leggibilità del codice.

Che dire:

void DoSomeInterestingImageManipulation(char *pImage)
{
    convertToFormatAbc(pImage); // allows x% space savings.
    *pResult = Foo(pImage);
}

void convertToFormatAbc(char *pImage)
{
    if (internalFormatNeedsDecompression(pImage))
    {
        decompress(pImage);
    }
}

boolean internalFormatNeedsDecompression(char *pImage)
{
    return pImage && pImage[0] = 0xFF;
}

Il punto che voglio illustrare è che dovresti mirare ad avere un codice di auto-documentazione. Ciò richiederà pochissimi commenti, se non del tutto. Se hai bisogno di commenti, cerca sempre la leggibilità, non i risparmi di spazio sullo schermo.

Secondo me, i commenti sopra o all'inizio di un blocco di codice indicano semplicemente che questo dovrebbe essere un metodo / una classe a sé stante.

Personalmente, scriverei lo stesso codice di questo:

///Converts the image to formatABC to save x% space
void DoSomeInterestingImageManipulation(char *pImage) {
    //Handle need for internal decompression
    if(pImage && pImage[0] == 0xFF) {
        ++pImage;
        //...
        //...
        //...
    }

    //Proceed normally
    *pResult = Foo(pImage);
}

Se devi commentare cosa fa qualcosa, allora scrivilo prima di quel qualcosa. Alcune persone preferiscono semplicemente leggere il tuo codice e saranno solo distratti dai tuoi commenti. Alcuni potrebbero voler leggere i tuoi commenti e non doverli cercare all'interno del tuo codice.
Inoltre, mantenere i commenti più brevi, brevi e chiari possibili. Se hai la sensazione di dover salvare alcune delle linee occupate dai commenti, piuttosto che prendere in considerazione la possibilità di fare commenti più brevi o rimuoverli completamente e scegliere invece degli identificatori auto-esplicativi.

Le tue giustificazioni non hanno senso per me. Non sono sicuro del motivo per cui vorresti salvare lo spazio verticale a meno che non prevedi di stamparlo tutto il tempo (e perché lo faresti) perché il risultato netto è un codice meno leggibile sullo schermo. Non lo vedo produttivo. In secondo luogo, come pensi di evitare di lasciare un suggerimento su come / perché qualcosa è stato fatto senza un commento di qualche descrizione? Non è la posizione del commento a dare quell'informazione, è il contenuto. È possibile costruire commenti in un modo più leggibile di questo e ci sono già un certo numero di esempi pubblicati.

Non so perché hai sviluppato questa abitudine - forse è qualcosa come una firma per te. Inoltre, essendo abituato, potresti trovare più facile leggere ora. Tuttavia, non trovo particolarmente leggibile il codice.

La risposta breve alla tua domanda è più difficile da leggere.

Non mi piace mescolare commenti e codice. Anche se il codice è un singolo { .

Ad esempio, alcuni IDE ti aiutano oscurando le linee che vengono commentate. Quando mischi codice e commento, puoi perdere questo codice colorante.

Un altro punto: preferisco usare un simbolo di commento per riga. In Java, ad esempio, preferisco usare molti //, uno per riga, invece di / * e * /.

In questo modo, durante il debug, posso usare / * * / per commentare il codice che verrà omesso senza dover vedere dove sto finendo i commenti di spiegazione

Anche se è solo un mio gusto, personalmente mi piace lo spazio extra (e la chiara struttura visiva) che ottengo dalla parentesi aperta. Questo è anche il motivo per cui ho sempre odiato la parentesi direttamente dopo la testa della funzione if / loop /. Inoltre, non mi piacciono i commenti sulla stessa riga del codice, perché di nuovo viola una chiara strutturazione.

Il più grande problema nello snippet di codice sono i commenti. In ogni caso sembra brutto e illeggibile. posiziona i commenti sulla linea separata.

void DoSomeInterestingImageManipulation(char *pImage)
{ 
    //This will convert the image to formatABC which allows x% space savings for storage
    if(pImage && pImage[0] == 0xFF)
    {
        //Process the extra case where image internal format needs decompression
        ++pImage;
        //...
        //...
        //...
    }

    //Proceed normally
    *pResult = Foo(pImage);
}

è molto meglio. Ho usato questo "stile" in passato ma ora ne uso uno migliore)

void DoSomeInterestingImageManipulation(char *pImage) { 
    //This will convert the image to formatABC which allows x% space savings for storage
    if(pImage && pImage[0] == 0xFF) {
        //Process the extra case where image internal format needs decompression
        ++pImage;
        //...
        //...
        //...
    }

    //Proceed normally
    *pResult = Foo(pImage);
}

Non mi dispiace così tanto, ma mi piacerebbe vedere qualche indentazione lì, quindi le parentesi graffe risaltano ancora facilmente durante la scansione del codice:

void DoSomeInterestingImageManipulation(char *pImage)
{   //This will convert the image to formatABC which allows x% space savings for storage
    if(pImage && pImage[0] == 0xFF)
    {   //Process the extra case where image internal format needs decompression
        ++pImage;
        //...
        //...
        //...
    }

    //Proceed normally
    *pResult = Foo(pImage);
}

In realtà mi piace mantenere lo spazio in più vuoto, ma forse è solo questione di abituarsi.

Mi piace lo stile e farei un ulteriore passo avanti e metto un commento sulla parentesi di chiusura per indicare cosa sta chiudendo.

L'unico cambiamento importante che farei è assicurarmi che la parentesi graffa di apertura sia un po 'più ovvia collocando lo spazio dopo di essa.

while (!fruitList.isEmpty())     // while there is fruit
{                                // ... do something with it
    Fruit fruit = fruitList.takeFirst();

    switch (fruit)      
    {
    case apple:
        MakeAppleSauce();
        break;

    case banana:
        MakeBananaBread();
        break;

    case grape:
        MakeWine();
        break;

    default:
        // Don't do anything (for now)
    }   // switch (fruit)
}       // while (!fruitList.isEmpty())