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