Questa è una vecchia domanda, ma inserirò comunque qui. Ho circa 20 anni di programmazione e gestione del codice di altre persone.
Penso che nominare la tua variabile con una breve indicazione del loro ambito sia davvero molto utile per la prossima persona (o te stesso) che guarderà il tuo codice.
Uno non guarda già il codice in un IDE con dei bei colori (e non riesco a ricordare cosa significano i colori e IDE diversi mostrano colori diversi, ecc.)
È vero, i metodi dovrebbero essere abbastanza brevi da non essere caricati con tonnellate di variabili e tonnellate di codice, ma anche su uno corto - quando si guarda un codice che non è affatto familiare, a volte è difficile dire se una variabile è una classe variabile, variabile locale o parametro del metodo.
Essere in grado di distinguere a colpo d'occhio rende molto facile rivedere il codice che non conosci.
Prendi questo esempio:
public <T> Page<T> moreLikeThis(MoreLikeThisQuery query, Class<T> clazz) {
int startRecord = 0;
ElasticsearchPersistentEntity persistentEntity = getPersistentEntityFor(clazz);
String indexName = isNotBlank(query.getIndexName()) ? query.getIndexName() : persistentEntity.getIndexName();
String type = isNotBlank(query.getType()) ? query.getType() : persistentEntity.getIndexType();
Assert.notNull(indexName, "No 'indexName' defined for MoreLikeThisQuery");
Assert.notNull(type, "No 'type' defined for MoreLikeThisQuery");
Assert.notNull(query.getId(), "No document id defined for MoreLikeThisQuery");
MoreLikeThisRequestBuilder requestBuilder = client.prepareMoreLikeThis(indexName, type, query.getId());
if (query.getPageable() != null) {
startRecord = query.getPageable().getPageNumber() * query.getPageable().getPageSize();
requestBuilder.setSearchSize(query.getPageable().getPageSize());
}
requestBuilder.setSearchFrom(startRecord);
if (isNotEmpty(query.getSearchIndices())) {
requestBuilder.setSearchIndices(toArray(query.getSearchIndices()));
}
if (isNotEmpty(query.getSearchTypes())) {
requestBuilder.setSearchTypes(toArray(query.getSearchTypes()));
}
if (isNotEmpty(query.getFields())) {
requestBuilder.setField(toArray(query.getFields()));
}
if (isNotBlank(query.getRouting())) {
requestBuilder.setRouting(query.getRouting());
}
if (query.getPercentTermsToMatch() != null) {
requestBuilder.setPercentTermsToMatch(query.getPercentTermsToMatch());
}
if (query.getMinTermFreq() != null) {
requestBuilder.setMinTermFreq(query.getMinTermFreq());
}
if (query.getMaxQueryTerms() != null) {
requestBuilder.maxQueryTerms(query.getMaxQueryTerms());
}
if (isNotEmpty(query.getStopWords())) {
requestBuilder.setStopWords(toArray(query.getStopWords()));
}
if (query.getMinDocFreq() != null) {
requestBuilder.setMinDocFreq(query.getMinDocFreq());
}
if (query.getMaxDocFreq() != null) {
requestBuilder.setMaxDocFreq(query.getMaxDocFreq());
}
if (query.getMinWordLen() != null) {
requestBuilder.setMinWordLen(query.getMinWordLen());
}
if (query.getMaxWordLen() != null) {
requestBuilder.setMaxWordLen(query.getMaxWordLen());
}
if (query.getBoostTerms() != null) {
requestBuilder.setBoostTerms(query.getBoostTerms());
}
SearchResponse response = requestBuilder.execute().actionGet();
return resultsMapper.mapResults(response, clazz, query.getPageable());
}
Ora, pensa a te stesso e guarda il codice (estratto da ElasticsearchTemplate dal progetto spring-data-elasticsearch - il codice che stavo esaminando e che mi ha spinto a cercare su Google ciò che la gente dice sulle convenzioni di denominazione).
- Qual è lo scode di
resultsMapper
?
- È
requestBuilding
un parametro?
- ecc ...
Ecco il mio semplice suggerimento su come le variabili dovrebbero essere denominate:
- Attributi statici di classe (cioè costanti): ALL_CAPS_WITH_UNDERSCORES (ad esempio
HOST_NAME
).
- Attributi di classe (vale a dire variabili di istanza di classe): camelCase (ad esempio
resultsMapper
).
- Parametri del metodo: prefissati con
a
(ad esempio aQuery
, aClazz
).
- Variabili locali: prefissate con
my
(ad esempio myIndexName
, myType
).
Il codice sopra diventa:
public <T> Page<T> moreLikeThis(MoreLikeThisQuery aQuery, Class<T> aClazz) {
int myStartRecord = 0;
ElasticsearchPersistentEntity myPersistentEntity = getPersistentEntityFor(aClazz);
String myIndexName = isNotBlank(aQuery.getIndexName()) ? aQuery.getIndexName() : myPersistentEntity.getIndexName();
String myType = isNotBlank(aQuery.getType()) ? aQuery.getType() : myPersistentEntity.getIndexType();
Assert.notNull(myIndexName, "No 'indexName' defined for MoreLikeThisQuery");
Assert.notNull(myType, "No 'type' defined for MoreLikeThisQuery");
Assert.notNull(aQuery.getId(), "No document id defined for MoreLikeThisQuery");
MoreLikeThisRequestBuilder myRequestBuilder = client.prepareMoreLikeThis(myIndexName, myType, aQuery.getId());
if (aQuery.getPageable() != null) {
myStartRecord = aQuery.getPageable().getPageNumber() * aQuery.getPageable().getPageSize();
myRequestBuilder.setSearchSize(aQuery.getPageable().getPageSize());
}
myRequestBuilder.setSearchFrom(myStartRecord);
if (isNotEmpty(aQuery.getSearchIndices())) {
myRequestBuilder.setSearchIndices(toArray(aQuery.getSearchIndices()));
}
if (isNotEmpty(aQuery.getSearchTypes())) {
myRequestBuilder.setSearchTypes(toArray(aQuery.getSearchTypes()));
}
if (isNotEmpty(aQuery.getFields())) {
myRequestBuilder.setField(toArray(aQuery.getFields()));
}
if (isNotBlank(aQuery.getRouting())) {
myRequestBuilder.setRouting(aQuery.getRouting());
}
if (aQuery.getPercentTermsToMatch() != null) {
myRequestBuilder.setPercentTermsToMatch(aQuery.getPercentTermsToMatch());
}
if (aQuery.getMinTermFreq() != null) {
myRequestBuilder.setMinTermFreq(aQuery.getMinTermFreq());
}
if (aQuery.getMaxQueryTerms() != null) {
myRequestBuilder.maxQueryTerms(aQuery.getMaxQueryTerms());
}
if (isNotEmpty(aQuery.getStopWords())) {
myRequestBuilder.setStopWords(toArray(aQuery.getStopWords()));
}
if (aQuery.getMinDocFreq() != null) {
myRequestBuilder.setMinDocFreq(aQuery.getMinDocFreq());
}
if (aQuery.getMaxDocFreq() != null) {
myRequestBuilder.setMaxDocFreq(aQuery.getMaxDocFreq());
}
if (aQuery.getMinWordLen() != null) {
myRequestBuilder.setMinWordLen(aQuery.getMinWordLen());
}
if (aQuery.getMaxWordLen() != null) {
myRequestBuilder.setMaxWordLen(aQuery.getMaxWordLen());
}
if (aQuery.getBoostTerms() != null) {
myRequestBuilder.setBoostTerms(aQuery.getBoostTerms());
}
SearchResponse myResponse = myRequestBuilder.execute().actionGet();
return resultsMapper.mapResults(myResponse, aClazz, aQuery.getPageable());
}
È perfetto? Io non la penso così Ma quanto sopra, per quanto riguarda le variabili, è ora più facile da leggere. Ci sono altre cose come l'allineamento e la spaziatura, che non entrerò in questa risposta in quanto non è correlata alla domanda, che renderebbe anche più facile la lettura.
Non ti piace il caso Camel? Bene, usa caratteri di sottolineatura, ecc., Ma anteponi le variabili locali e i tuoi parametri per renderli diversi rispetto alle variabili di istanza di classe.
Non ti piace a
e my
- bene, resta coerente nel tuo progetto e usa qualcos'altro ... ma usa qualcosa.
Regola 1: consistenza all'interno del progetto.
La regola n. 2: rende facile la lettura e non richiede che il lettore sappia tutto prima che possa imparare.