Spiegazione della sintassi nuova o non comune nei commenti [duplicato]

Nel contesto di ABAP puoi raramente aspettarti che tutti abbiano familiarità con tutte le nuove funzionalità perché:

1. ABAP ha una storia così lunga e i costrutti del linguaggio antico sono sempre incontrati (sto attualmente modificando un rapporto che usa un database logico e fa un uso eccessivo delle tabelle con le linee di intestazione).
2. Gli stessi SAP utilizzano raramente le nuove funzionalità per garantire la compatibilità con i sistemi non aggiornati alle versioni più recenti, quindi raramente si incontrano le nuove funzionalità "in the wild".
3. I corsi di formazione SAP sono molto costosi, quindi le aziende evitano di mandare persone a cui disperatamente non hanno bisogno per il loro lavoro. I corsi delta che spiegano le nuove funzionalità sono raramente considerati essenziali.

Quando la tua organizzazione non è aggiornata nelle ultime pratiche di sviluppo, potresti prendere in considerazione la tua missione di aggiornarle in modo che non siano necessarie spiegazioni di sintassi insolita. Quando questa non è un'opzione (non hai tempo, risorse e non senti che questa è una tua responsabilità), dovresti evitare le nuove funzionalità per non confondere gli altri membri del team o commentarli.

Ricorda le regole dei buoni commenti:

• Il principiante spiega la sintassi
• L'apprendista spiega cosa sta succedendo
• L'esperto spiega perché sta succedendo

Bad:

" This uses the new line_exist operator in 740 which replaces READ TABLE
IF line_exists( itab[ carrid = 'AE' ] ).
    PERFORM foobar.
ENDIF.

Quando conosco quell'operatore questo commento non mi aiuta affatto. Inoltre, potrei ridere di te chiamandolo "nuovo" perché potrebbe essere l'anno 2028 e quell'operatore è stato dichiarato obsoleto anni fa. Quando non conosco l'operatore, mi hai appena mandato su Google 10 minuti invece di aiutarmi a capire il tuo codice.

Meglio:

" When any position has the carrier 'AE', we need to do the foobar operation
IF line_exists( itab[ carrid = 'AE' ] ).
    PERFORM foobar.
ENDIF.

Questo mi dice cosa sta succedendo, quindi non ho nemmeno bisogno di capire cosa faccia questa nuova lingua. Quando non lo sapevo prima, mi hai appena dimostrato quello che fa, quindi ho imparato qualcosa da te. E anche quando lo so già, il tuo commento potrebbe essere più leggibile del tuo codice, aiutandomi a capire il tuo programma.

Ancora meglio:

" Anytime there is at least one flight by carrier AE on the
" flight list, the foobar operation must be performed to prevent 
" all the foobaz from getting confabulated.
IF line_exists( itab[ carrid = 'AE' ] ).
    PERFORM foobar.
ENDIF.

Non mi dice solo cosa sta succedendo, ma anche quale scopo soddisfa.

Contrariamente ad altre risposte, direi di no. Il codice dovrebbe essere auto-documentato il più possibile. Queste semplici cose non dovrebbero essere spiegate nel codice.

Non conosco SAP, ma una semplice query di google ha indicato la pagina di riferimento SAP al line_exists function.

Se i manutentori e gli sviluppatori non sono aggiornati, l'azienda deve sviluppare una strategia per mantenerli aggiornati.

Penso che dipenda dalla situazione.

In questo esempio, la documentazione come questa appartiene a un file README. ^* Se si utilizza costantemente la nuova sintassi, il codice sarà praticamente irriconoscibile per un programmatore che conosce solo lo stile precedente. I tuoi manutentori ti ringrazieranno se avviserai in anticipo che non conoscono realmente questa lingua . Vorrei:

1. Avvia ogni file sorgente con un commento in grassetto che questo file usa la nuova sintassi:

   ***********************************************
   * ### This file uses the NEW ABAP SYNTAX  ### *
   * ### introduced in NetWeaver 7.4.        ### *
   * ### Please see README.html for details. ### *
   ***********************************************
   

2. Nel README, spiega brevemente le modifiche alla sintassi e fornisci collegamenti (quindi README. html ) a esercitazioni e riferimenti.

Questo ha due vantaggi:

1. Puoi riutilizzare il README su più progetti. Non ripeterti!

2. Il tuo codice non sarà un mezzo commento. Sembra che la nuova sintassi sarà presente in ogni file. Spiegare la sintassi, anche se brevemente, ovunque tu la usi sarà noioso da parte tua e difficile da leggere per il tuo maintainer.

* _{Caveat: tutto ciò che so di ABAP ho imparato dai link nel tuo post. Si prega di non considerare questo un parere di esperti.}

** _{A proposito, il commento del blocco campione sopra riportato qui è concesso in licenza CC0 1.0 :). Sentiti libero di copiarlo se è conveniente farlo!}

In questo caso, qualcuno che non ha familiarità con gli aggiornamenti potrebbe semplicemente cercare line_exists e andare avanti.

Per qualcosa di meno ricercabile, potresti voler lasciare un commento che chiami semplicemente le nuove funzionalità che stai utilizzando in modo che sia più facile trovare la documentazione aggiornata. Se si utilizzano queste funzionalità in più di un paio di posizioni, inserire tale avviso in un file readme anziché nei commenti.

Non mi preoccuperei di spiegare la sintassi se c'è già un'ampia documentazione da un'altra fonte, risparmia il tuo sforzo per documentare le cose che tu sviluppi.

Nota: non ho molta familiarità con ABAP, quindi sto rispondendo come se qualcuno mi chiedesse di usare lambda in Java, nella consapevolezza che il problema è simile (AFAIK lo è). Se ho torto, per favore informami.

Questo non appartiene ai commenti (parte del codice) in quanto è un problema di specifica del progetto. In realtà, non dovrebbe essere un programmatore che decide di utilizzare le nuove funzionalità, ma il project manager o anche il proprietario del prodotto che deciderà con quale versione / i di ABAP il progetto dovrebbe essere compatibile.

Da qualche parte nella documentazione del progetto dovrebbe essere scritto qualcosa come "Supporta ABAP X". Ora:

• Se X è 1990, non dovresti usare nessuna funzionalità che non sia compatibile con ABAP 1990. Se ritieni che quelle nuove funzionalità diano così tanto valore aggiunto che è auspicabile un cambio di X al 2015, parla con le persone incaricate di eseguire tale decodifica in modo da aggiornare le specifiche del progetto (o meno).

• Se X è il 2015, ogni nuovo programmatore saprà che deve avere una certa conoscenza delle nuove funzionalità solo per essere in grado di leggere il codice, spetta a loro imparare (o richiedere una formazione per) tale versione della lingua, se non ci sono ancora familiari.

Da un punto di vista penso che questo sia un po 'un problema X-Y.

Per il mio esempio mi piacerebbe che chiunque leggesse questo considerasse la recente revisione del C ++ 11 di C ++. In particolare, vorrei concentrarmi sull'operatore constexpr . Lo scopo è quello di consentire a determinate funzioni di essere eseguite dal compilatore (ad esempio una funzione fattoriale) in fase di compilazione, impedendo così di calcolare i valori costanti in fase di esecuzione.

Dite per l'argomento che sono in un team di sviluppo pieno di sviluppatori C ++ che non hanno letto su nessuna delle funzionalità di C ++ 11 (diciamo che siamo nel 2012 per rendere questo scenario un po 'più realistico). Prendo la nostra funzione int factorial(int n) e aggiungo constexpr . Ora devo documentarlo. Scrivo un commento che spieghi perché ho aggiunto constexpr o quel genere di cose appartiene davvero al registro delle modifiche del progetto?

Direi che i commenti servono a spiegare lo stato attuale del codice, non i cambiamenti che ha attraversato. Non lasci un commento per ogni bug che hai rimosso, ne prendi nota in un registro delle modifiche o in un log degli errori. Allo stesso modo, i motivi per rendere factorial a constexpr dovrebbero essere espressi nel registro delle modifiche.

Il commento dovrebbe comunque essere cambiato, in quanto ho cambiato il comportamento della funzione. Non funziona più in fase di esecuzione, ma viene eseguito in fase di compilazione. Quindi cambio il commento da //Calculates the result of the factorial operation a //Calculates the result of the factorial operation at compile time .

"Aha, hai appena spiegato la funzione" Sento che la gente pensa. No, non ho. Quello che ho fatto è fare in modo che il commento descriva il comportamento della funzione. Quello che non ho fatto è spiegare tutti gli avvertimenti impliciti nell'uso di constexpr (cioè non ho spiegato in quali situazioni applicando constexpr a una funzione si ottiene un errore di compilazione).

Se avessi modificato qualche sintassi per utilizzare un modulo più leggibile, non avrei documentato tale modifica in un commento perché non avrei modificato il comportamento del codice stesso. Invece avrei documentato la modifica nel registro delle modifiche.

Ora in risposta ad alcuni punti specifici:

assume this syntax is the recommended approach

Se è l'approccio raccomandato, dovrebbe essere usato. L'unico motivo per non usarlo sarebbe se rompe qualcosa o non sia ancora ampiamente supportato dagli strumenti che usi (come alcune delle funzionalità di C ++ 11).

On the one hand, comments are there to facilitate maintenance and if I provide that explanation I could save a future developer a lot of effort and reading.

E li priva dell'apprendimento di tutti i dettagli di un linguaggio? Non si dà una chiave a qualcuno e si dimentica che è regolabile. Se uno degli altri programmatori manca un fatto importante perché ha letto il tuo sommario invece delle avvertenze complete di una funzione di sintassi, sarà effettivamente colpa tua se introdurranno un bug a causa di esso. Certo sarà colpa loro per non aver letto la documentazione, ma perché non l'hanno letto? Perché hanno saputo della funzionalità attraverso un commento.

once the project is delivered and they can be notorious for being stuck in "legacy mode"

E costringendoli a leggere la documentazione, li stai costringendo a uscire da questa abitudine. Questa è una cosa buona ™ . Per quello che vale ho scaricato il pdf, la nuova sintassi è molto più in linea con il pensiero moderno. Ancora una volta, questa è una cosa buona ™ , dovresti incoraggiare l'adozione di nuove funzionalità quando migliorano la leggibilità, le prestazioni o la manutenibilità del tuo codice. Il tempo trascorso a leggere la documentazione non è mai uno spreco se il lettore impara qualcosa.