Dove devo inserire commenti nel mio "codice di autocertificazione"?

2

Attualmente sto sviluppando una web-app da sola e ho deciso di usare nomi descrittivi di variabili e metodi (a volte a scapito della brevità) per minimizzare i commenti. Il piano era di codificare ogni metodo usando questa strategia, quindi commentare dopo aver completato il metodo su cui stavo lavorando.

Tuttavia, ho scoperto che dopo (più o meno) tutti i metodi che ho completato, i commenti in linea sembravano superflui. Continuo a seguire le convenzioni Javadoc per classi e metodi, ma per ora il mio codice è per la maggior parte completamente privo di commenti in linea.

Fortunatamente, sono ancora relativamente in anticipo nel processo di sviluppo e tutti i meccanismi dei metodi sono freschi nella mia testa, in caso di situazioni in cui ho bisogno di scrivere commenti in linea.

Questa è una buona strategia? In caso negativo, dove dovrei includere i commenti in linea? Ho incluso uno dei miei metodi qui sotto per illustrare quanto è attualmente documentato da solo.

(Sto usando Pelops, che è una libreria Java utilizzata per accedere a un database Cassandra. Senza entrare troppo nel modello dati di Cassandra, una riga corrisponde fondamentalmente a una tupla di database relazionale, e una colonna corrisponde a una colonna in una tabella del database delle relazioni).

Mi piacerebbe pensare che anche senza conoscere Pelops o Cassandra, quello sarà in grado di capire cosa sta succedendo nel codice. È questo il caso? In caso contrario, dove posso inserire commenti per renderlo cristallino? Spero di astrarre eventuali suggerimenti sul posizionamento dei commenti in questo codice in tutti gli altri metodi che ho scritto finora.

/**
     * Gathers a user's ID and first name from the database, creates a random activation code for that user and stores
     * it in the database, and sends an activation e-mail to that user.

     * @param eMail                           a String representation of the e-mail of the user that the e-mail is being sent for
     * @throws MyAppConnectionException      if any of the queries is unable to be executed or a problem arises because of one, or if a problem arises while sending the e-mail
     */
    public static void generateAndSendActivation(String eMail) throws MyAppConnectionException, MyAppActivationException
    {
        eMail = eMail.toLowerCase();

        try
        {
            Selector userIDSelector = Pelops.createSelector(pool);
            Column userIDColumn = userIDSelector.getColumnFromRow("Users_By_Email", eMail, "User_ID", ConsistencyLevel.ONE);
            String userIDString = new String(userIDColumn.getValue());

            Selector firstNameAndStatusSelector = Pelops.createSelector(pool);
            SlicePredicate firstNameAndStatus = Selector.newColumnsPredicate("First_Name", "Status");
            List<Column> firstNameAndStatusColumns = firstNameAndStatusSelector.getColumnsFromRow("Users", userIDString, firstNameAndStatus, ConsistencyLevel.ONE);

            char statusChar = Selector.getColumnValue(firstNameAndStatusColumns, "Status").toChar();

            if(statusChar == 'N')
            {
                String firstNameString = Selector.getColumnStringValue(firstNameAndStatusColumns, "First_Name");

                String activationCode = createRandomCode();
                String activationHash = BCrypt.hashpw(activationCode, BCrypt.gensalt());

                Mutator storeActivationHashMutator = Pelops.createMutator(pool);
                storeActivationHashMutator.writeColumn("Users", userIDString,
                        storeActivationHashMutator.newColumn("Activation_Code", activationHash)
                        );

                storeActivationHashMutator.execute(ConsistencyLevel.ONE);
                sendEmail(firstNameString, userIDString, eMail, activationCode, "sendActivationCode");
            }
            else
            {
                throw new MyAppActivationException("User with ID " + userIDString + "tried to activate an already activated account");
            }

        }
        catch(NotFoundException nfe)
        {
            MyAppQueryException bqe = new MyAppQueryException("Account for user with e-mail " + eMail + " not found. Cannot send activation code", nfe);
            bqe.accountDoesNotExist = true;
            throw bqe;
        }
        catch(PelopsException pe)
        {
            MyAppQueryException be = new MyAppQueryException("Unable to carry out one of the operations required to generate and store activation code", pe);
            throw be;
        }
        catch(MyAppMailException bme)
        {
            throw bme;
        }
    }
    
posta Kevin 23.05.2011 - 19:47
fonte

3 risposte

4

Prima di tutto, penso che dovresti dividere tale metodo in più ed evitare numeri magici / caratteri

per esempio può essere simile a

User user = retrieveUser(email);
if(user.isNew()){
     String activationCode = calcActivationCode();
     addUserToDb(activationCode );
     sendEmailWithActivationCode(email, activationCode);
}

E quindi implementa retrieveUser , addUserToDb , addsendEmail

    
risposta data 23.05.2011 - 20:08
fonte
2

Scrivo spesso codice proprio come questo. Con molto poco, spesso niente, scritto per i commenti in linea. Una buona pratica sarebbe quella di avere i tuoi test come documentazione. Se vuoi sapere che cosa dà un'occhiata ai suoi test unitari in quanto racconteranno la migliore storia.

Inoltre, potresti voler creare un'astrazione attorno all'implementazione dell'accesso ai dati. È possibile creare un DAO per nascondere l'implementazione effettiva nel codice che utilizza l'accesso ai dati. Ciò renderebbe più chiaro che qualcosa è stato creato / aggiornato / cancellato / letto abbastanza facilmente nel codice che lo utilizza. Se hanno bisogno di sapere cosa sta succedendo nell'attuale implementazione, dovranno trovare quello che viene usato (probabilmente solo la tua implementazione), e a quel punto, i nomi dei metodi dovrebbero essere abbastanza descrittivi.

In definitiva, fai ciò che funziona per te. Se si codificano spesso le modifiche, potrebbe non avere senso avere molti commenti, poiché potrebbe essere difficile aggiornare la documentazione così spesso. Poi di nuovo, se stai bene cambiando documentazione spesso, questo non sarebbe un problema.

    
risposta data 23.05.2011 - 19:59
fonte
1

Penso che l'uso di buoni nomi, l'uso di javadoc per classe / per-metodo, laddove sia utile, e la conservazione di metodi abbastanza brevi siano buoni punti di partenza.

Per quanto riguarda i commenti incorporati: come tutti i commenti, non ci sono regole rigide e veloci; e a volte un po 'fa molto. Tuttavia, non credo che quello non abbia mai bisogno di loro, né che questo dovrebbe essere un obiettivo. Ovviamente non dovresti provare ad aggiungere alcun numero specifico di commenti (sia in base a misure assolute o relative).

Per quello che vale, penso che i commenti in linea mi sembrino molto utili quando spiegano il flusso di controllo. Nel tuo caso, ad esempio, si potrebbe prendere in considerazione la possibilità di commentare sopra la frase 'if (statusChar ==' N ')'. Il problema con i commenti per metodo è che non sono proprio accanto al luogo esatto in cui accadono le cose.

    
risposta data 23.05.2011 - 20:09
fonte

Leggi altre domande sui tag