Örneğin adlandırma kuralları, yerel ve parametre değişkenleri [kapalı]

Projelerimize (özellikle Java / JEE projeleri) uygulanacak kıdemli bir geliştirici kodlama sözleşmeleri ile görüşüyordum. Önerdiği bir sözleşmeye katılmadım:

Örnek değişken adları "_" ile başlamalı, "loc" ile yerel değişkenler ve "par" ile yöntem parametreleri olmalıdır.

Kısa süreli bellek ve okunabilirlik için argümanlar ortaya koyarken, okunabilirliği azalttığını, Eclipse gibi IDE'lerin türlerine bağlı olarak farklı şekillerde olduğunu kabul etmedim ve bu sorun iyi bir sınıf ve yöntem tasarımı ile önlenecektir.

Benim görüşümü destekleyen (ya da buna karşı çıkan) herhangi bir fikriniz, tartışmanız ya da çalışmanız var mı?

Wikipedia'nın konuyla ilgili söylediği gibi - java adlandırma kuralları,

Yerel değişkenler, örnek değişkenler ve sınıf değişkenleri lowerCamelCase'de de yazılır. Her ikisine izin verilse de, değişken adları alt çizgi (_) veya dolar işareti ($) karakterleriyle başlamamalıdır. Bazı kodlama kuralları, okuma ve programın daha iyi anlaşılması için tüm örnek değişkenlerin önekini yapmak için alt çizgilerin kullanılması gerektiğini belirtir.

Kodlama standartları konusundaki tecrübelerime göre, Instance değişken adları "_" ile başlayan wikipedia standartlarının dediği kadar iyi değil.

"loc" ile yerel değişkenler ve "par" ile yöntem parametreleri, bir değişken başlangıç ​​noktası ve kapsamı tanımlamanın kolay olacağını, ancak bir gün bakım için kodunuzdan geçebilecek diğer programcılar için değil, sizin için olmalıdır .

Gereğince Temiz Kod yöntemleri hakkında şartname bu kısa olduğu kadar onlar aklın eşlenmemelidir gerektiğini okunabilirliği ve değişkenler adları için yapabileceği olmalı, bunlar yöntem gerçekleştirmenizi operasyonun alakalı olmalıdır.

Üye / Kapsam Önekleri, artık üye değişkenlere m_ ile önek eklemeniz gerekmez. Sınıflarınız ve işlevleriniz onlara ihtiyacınız olmayacak kadar küçük olmalıdır. Ve üyeleri farklı kılmak için vurgulayan veya renklendiren bir düzenleme ortamı kullanmalısınız.

public class Part {
private String m_dsc; // The textual description
void setName(String name) {
m_dsc = name;
}
}

public class Part {
String description;
void setDescription(String description) {
this.description = description;
}
}

Ayrıca, insanlar adın anlamlı kısmını görmek için öneki (veya soneki) görmezden gelmeyi öğrenir. Kodu ne kadar çok okursak, önekleri o kadar az görürüz. Sonunda önekler görünmeyen karmaşa ve eski kodun bir işareti haline gelir.

Bu eski bir soru, ama yine de buraya göndereceğim. 20 yıldan fazla bir süredir programlama ve başkalarının kodlarıyla ilgilenmem gerekiyor.

Değişkeninizi kapsamlarına göre kısa bir gösterimle adlandırmanın, kodunuza bakacak bir sonraki kişi (veya kendiniz) için gerçekten yararlı olduğunu düşünüyorum.

Bir zaten IDE güzel renkler ile kod bakmıyor (ve renklerin ne anlama geldiğini hatırlayamıyorum ve farklı IDE farklı renkler, vb gösterir).

Doğru, yöntemler yeterince kısa olmalı, bu yüzden tonlarca değişken ve ton kodla yüklü değil, kısa kodda bile - tamamen tanıdık olmayan koda baktığınızda, bir değişkenin sınıf değişkeni olup olmadığını söylemek zor olabilir, yerel değişken veya yöntem parametresi.

Bir bakışta ayırt edebilmek, bilmediğiniz kodu incelemeyi çok kolaylaştırır.

Bu örneği ele alalım:

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

Şimdi, kendinize zaman ayırın ve koda bakın (ElasticsearchTemplate'ten spring-data-elasticsearch projesinden çıkarıldı - gözden geçirdiğim kod, insanların Google’da adlandırma kuralları hakkında söylediklerini aramamı istedi.

• Sonuç ne resultsMapper?
• Mı requestBuildingbir parametre?
• vb...

Değişkenlerin nasıl adlandırılması gerektiğine dair basit önerim:

• Sınıf statik öznitelikleri (yani sabitler): ALL_CAPS_WITH_UNDERSCORES (örn. HOST_NAME).
• Sınıf nitelikleri (yani, sınıf örneği değişkenleri): camelCase (örn. resultsMapper).
• Yöntem parametreleri: öneki a(örneğin aQuery, aClazz).
• Yerel değişkenler: öneki my(örneğin myIndexName, myType).

Yukarıdaki kod:

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());

}

Mükemmel mi? Ben öyle düşünmüyorum. Ancak, değişkenler söz konusu olduğunda, yukarıdakilerin okunması artık daha kolay. Soruyla ilgili olmadığı için bu cevapta girmeyeceğim hizalama ve boşluk gibi başka şeyler de var, bu da okumayı kolaylaştıracak.

Camel Case'i sevmiyor musun? İnce, alt çizgi vb. Kullanın, ancak bunları sınıf örneği değişkenlerinden farklı kılmak için yerel değişkenlerinize ve parametrelerinize ön ek uygulayın.

Sevmiyorsunuz ave my- iyi, sadece projenizde tutarlı kalın ve başka bir şey kullanın ... ama bir şey kullanın.

Kural # 1: Proje içindeki tutarlılık.

Kural # 2: Okumayı kolaylaştırın ve okuyucunun öğrenmeden önce her şeyi bilmesini gerektirmez.

Bu büyük ölçüde bir tercih meselesidir ve bu nedenle 'doğru' bir cevap yoktur. Yani, bu soru aslında kapalı olabilir. Ama önce, sana tamamen katıldığımı söyleyeyim. Ön ekler, benim görüşüm açısından görünürlüğü azaltır. Herhangi bir önek olması durumunda, IDE'nizin zaten vurgulayabileceği şeyler için değil , Macar Gösteriminin orijinal niyeti gibi daha yararlı şeyler için kullanılmaları gerçeğine bakalım .

Ben ikisi arasında çok az, eğer varsa, gerçekten çok az, çünkü parametreler ve yerel değişkenler için örneğin veri (değişkenler veya sabitler) ve lower_case için COCCase kullanın. Asla, hiç topsız olduğu için headlessCamelCase kullanmıyorum: headlessCamelCase olması amaçlanmış olsa bile, tek bileşenli bir tanımlayıcı küçük harfe benziyor.