Suggerimenti sulla codifica coding-tips

CAUTION
AEM 6.4 ha raggiunto la fine del supporto esteso e questa documentazione non viene più aggiornata. Per maggiori dettagli, consulta la nostra periodi di assistenza tecnica. Trova le versioni supportate qui.

Utilizza taglibs o HTL il più possibile use-taglibs-or-htl-as-much-as-possible

L'inclusione degli script in JSP rende difficile il debug dei problemi nel codice. Inoltre, includendo gli script in JSP, è difficile separare la logica di business dal livello di visualizzazione, che è una violazione del principio di responsabilità singola e del modello di progettazione MVC.

Scrivi codice leggibile write-readable-code

Il codice viene scritto una volta, ma letto molte volte. Trascorrere un po' di tempo in anticipo per pulire il codice che scriviamo pagherà dividendi lungo la strada come noi e altri sviluppatori hanno bisogno di leggerlo più tardi.

Scegliere i nomi che rivelano le intenzioni choose-intention-revealing-names

Idealmente, un altro programmatore non dovrebbe dover aprire un modulo per capire cosa fa. Allo stesso modo, dovrebbero essere in grado di dire cosa fa un metodo senza leggerlo. Meglio possiamo abbonarci a queste idee, più facile sarà leggere il nostro codice e più velocemente saremo in grado di scrivere e cambiare il nostro codice.

Nella base di codice AEM vengono utilizzate le seguenti convenzioni:

  • Viene denominata una singola implementazione di un’interfaccia <Interface>Impl, vale a dire ReaderImpl.
  • Sono denominate più implementazioni di un'interfaccia <Variant><Interface>, vale a dire JcrReader e FileSystemReader.
  • Le classi base astratte sono denominate Abstract<Interface> o Abstract<Variant><Interface>.
  • I pacchetti sono denominati com.adobe.product.module. Ogni artefatto Maven o bundle OSGi deve avere un proprio pacchetto.
  • Le implementazioni Java vengono inserite in un pacchetto impl sotto la loro API.

Tieni presente che queste convenzioni non devono necessariamente essere applicate alle implementazioni dei clienti, ma è importante che le convenzioni siano definite e rispettate in modo che il codice possa rimanere gestibile.

Idealmente, i nomi dovrebbero rivelare le loro intenzioni. Un test comune del codice per quando i nomi non sono chiari come dovrebbero essere è la presenza di commenti che spiegano a cosa serve la variabile o il metodo:

Non chiaro
Cancella
int d; //tempo trascorso in giorni
int elapsedTimeInDays;
//Ottenere immagini con tag
public List getItems() {}
public List getTaggedImages() {}

Non ripeterti don-t-repeat-yourself

DRY afferma che lo stesso set di codice non deve mai essere duplicato. Questo vale anche per cose come le stringhe letterali. La duplicazione del codice apre la strada ai difetti ogni volta che qualcosa deve cambiare e deve essere ricercato ed eliminato.

Evitare regole CSS nude avoid-naked-css-rules

Le regole CSS devono essere specifiche per l’elemento di destinazione nel contesto dell’applicazione. Ad esempio, una regola CSS applicata a .content .center sarebbe eccessivamente ampio e potrebbe potenzialmente influenzare molti contenuti nel sistema, richiedendo ad altri di ignorare questo stile in futuro. .myapp-centertext sarebbe una regola più specifica mentre specifica centrato text nel contesto dell'applicazione.

Eliminazione dell’utilizzo di API obsolete eliminate-usage-of-deprecated-apis

Quando un’API è obsoleta, è sempre meglio trovare il nuovo approccio consigliato invece di basarsi sull’API obsoleta. In questo modo gli aggiornamenti saranno più semplici in futuro.

Scrivi codice localizzabile write-localizable-code

Le stringhe che non vengono fornite da un autore devono essere racchiuse in una chiamata al dizionario i18n di AEM tramite I18n.get() in JSP/Java e CQ.I18n.get() in JavaScript. Questa implementazione restituirà la stringa che gli è stata passata se non viene trovata alcuna implementazione, quindi offre la flessibilità di implementare la localizzazione dopo l'implementazione delle funzionalità nella lingua primaria.

Esci dai percorsi delle risorse per la sicurezza escape-resource-paths-for-safety

Anche se i percorsi nel JCR non devono contenere spazi, la loro presenza non deve causare l'interruzione del codice. Jackrabbit fornisce una classe di utilità di testo con escape() e escapePath() metodi. Per i JSP, l’interfaccia Granite espone un granite:encodeURIPath() EL funzione .

Utilizza l’API XSS e/o HTL per proteggere dagli attacchi di script tra siti diversi use-the-xss-api-and-or-htl-to-protect-against-cross-site-scripting-attacks

AEM fornisce un’API XSS per pulire facilmente i parametri e garantire la sicurezza dagli attacchi di script tra siti diversi. Inoltre, HTL dispone di queste protezioni integrate direttamente nel linguaggio dei modelli. È disponibile un foglio di supporto API da scaricare all’indirizzo Sviluppo - Linee guida e best practice.

Implementare la registrazione appropriata implement-appropriate-logging

Per il codice Java, AEM supporta slf4j come API standard per la registrazione dei messaggi e deve essere utilizzato insieme alle configurazioni rese disponibili tramite la console OSGi per motivi di coerenza nell’amministrazione. Slf4j espone cinque diversi livelli di registrazione. È consigliabile utilizzare le seguenti linee guida quando si sceglie a quale livello registrare un messaggio:

  • ERRORE: Quando qualcosa è rotto nel codice e l'elaborazione non può continuare. Questo si verificherà spesso a seguito di un'eccezione imprevista. In genere è utile includere tracce di stack in questi scenari.
  • AVVERTENZA: Quando qualcosa non funziona correttamente, ma l'elaborazione può continuare. Questo sarà spesso il risultato di un'eccezione che ci aspettavamo, come PathNotFoundException.
  • INFORMAZIONI: Informazioni utili per il monitoraggio di un sistema. Tieni presente che questa è l’impostazione predefinita e che la maggior parte dei clienti lo lascerà in posizione nei propri ambienti. Pertanto, non utilizzarlo eccessivamente.
  • DEBUG: Informazioni di livello inferiore sull’elaborazione. Utile quando si esegue il debug di un problema con il supporto.
  • TRACE: Informazioni di livello più basso, ad esempio metodi di immissione/uscita. In genere questo viene utilizzato solo dagli sviluppatori.

Nel caso di JavaScript, console.log deve essere utilizzato solo durante lo sviluppo e tutte le istruzioni di registro devono essere rimosse prima del rilascio.

Evitare la programmazione di cult cargo avoid-cargo-cult-programming

Evita di copiare il codice senza capire cosa fa. In caso di dubbi, è sempre meglio chiedere a qualcuno che ha più esperienza con il modulo o l’API su cui non sei chiaro.

recommendation-more-help
2315f3f5-cb4a-4530-9999-30c8319c520e