Anlamlı özlü yöntem adlandırma kuralları

Son zamanlarda açık kaynaklı bir projeyi yayınlamaya başladım, kütüphanenin tek kullanıcısıyken isimleri umursamıyordum, ama öğrenmeyi kolaylaştırmak için her yönteme akıllı isimler atamak istediğimi biliyorum ama aynı zamanda kullanmam gerekiyor özlü isimler böylece yazmak da kolaydır.

Adlandırma ile ilgili bazı kurallar hakkında düşünüyordum, yalnızca harfleri ya da basit notları önemseyen birçok kuralın farkındayım. Burada anlamlı ama henüz özlü isimlendirme kurallarına bakıyorum.

Örneğin, bu benim ilgilendiğim kuralların bir parçası olabilir:

• Mevcut bir öğe bir hedefe eklenecekken Ekle'yi, yeni bir öğe oluşturulurken ve bir hedefe eklendiğinde Oluştur'u kullanın.
• Var olan bir öğe bir hedeften kaldırılacaksa Kaldır'ı, bir öğe kalıcı olarak kaldırılacağı zaman sil'i kullanın.
• AddXXX yöntemlerini RemoveXXX ile eşleştirin ve CreateXXX yöntemlerini DeleteXXX yöntemleriyle eşleştirin, ancak bunları karıştırmayın.

Yukarıdaki örneklerin gösterdiği gibi, İngilizce dilbilgisi ve kelime anlamlarına uygun adlandırma yöntemleri ve diğer öğelere yardımcı olacak çevrimiçi materyaller bulmak istiyorum.

Yukarıdaki rehber anadili İngilizce olan kişiler için sezgisel olabilir, ancak benim için ingilizcenin ikinci dilim olduğunu ve bunun gibi şeyleri anlatmam gerekiyor.

Adlandırma. Yazılım geliştirme ile ilgili en zor şeylerden biri :)

Bir şeyi adlandırdığımda önceliklerim burada:

• Dilimin deyimlerini takip et. Ruby altını çizmeyi sever. Javascript, deve olayını sever. Hangi dilde olursanız olun takip edilecek kural.
• API'nin amacını ortaya çıkarır. "Send_http_data" değil, "post_twitter_status"
• Uygulama ayrıntılarını sızdırmaktan kaçının. Bir değişkenin türüne önek ekleyerek
• Önceki kurallara uymadan gerekenden daha fazla karakter kullanmaz.

Açıkçası bu oldukça basit bir yaklaşım. Adlandırma nüanslıdır.

Daha fazla araştırma için, Metot Kodlama Sanatı'nı okumanızı tavsiye ederim , zira metot adlandırma konusunda bazı mükemmel, özlü önerilerde bulunur. Daha fazla araştırma için Bob Martin'in Temizlik Kodunu daha fazla tavsiye edemiyorum

Adlandırma için bir stil veya konvansiyonu kodlama eğilimi, bazı durumlarda örneğin Macar Notasyonu kullanmak gibi, bugünlerde kötü uygulama olarak kabul edilen alışkanlıklara yol açabilir. Basit cevap, konvansiyon ve stilin ayrı ayrı belirlenecek ayrı bir şeymiş gibi adlandırılmasının unutulması ve bunun yerine sisteminizdeki her şeyin gerçekte neyi temsil ettiğine göre adlandırılmaya odaklanmasıdır. Her bir yöntemin işlevselliğini kısıtlı olarak yalnızca tek bir şey yapacak şekilde sınırlarsanız ve yöntem adınız yöntemin yapması gereken şeyi açıklarsa, yöntem adları doğal olarak kısa olur.

Değişkenler, alanlar, sınıf ve dosya adları başka bir şeydir. Değişken isimleri çok uzun sürerse, bu öğeleri ya çok ayrıntılı bir şekilde tanımlamaya çalışıyorsunuzdur ya da daha küçük parçalara bölünmesi gereken ya da belki daha soyut bir şekilde anlatılması gereken karmaşık bir şeyi temsil ediyorsunuzdur. tavır.

Günün sonunda, tüm satırı alan isimlerle çirkin bir koddan kaçınmak veya değerlerini soyacak kadar glib olmaktan kaçınmak istiyorsunuz.

Benim için, bir şey için iyi bir isim bulmak her zaman onu varlığını haklı çıkarmak zorunda olan bir nesne olarak düşünmeye geri döner . Kendine sor:

• Sınıf / yöntem / değişken ne yapar, yani genel amacı ne ve ne içindir?
• Özel olarak amacı ile ilgili olarak ne iletişim kurması gerekiyor, yani adın içinde bulunması gereken temel kısım nedir?

Çoğu geliştirici, okunabilirliğin , adlandırma söz konusu olduğunda her zaman çok önemli olduğu konusunda hemfikirdir . Sadece kod yazmayın, böylece yazarken ne demek istediğinizi anlayın, kod yazıp gelecekte bir noktada ilk kez görünen birisinin çok fazla düşünmek zorunda kalmadan ne demek istediğini bilmesi için yazın. Kodu yalnızca bir kez yazacaksınız, ancak kullanım ömrü boyunca büyük olasılıkla birçok kez düzenlenmesi ve daha çok kez okuması gerekecektir.

Kod kendini belgeliyor olmalıyani, adlandırma bir şeyin ne yaptığını açıkça belirtmelidir. Bir kod satırının bir yorumda ne yaptığını açıklamanız gerekiyorsa ve işleri yeniden adlandırmak onu yeterince iyileştirmiyorsa, orijinal satırı okumak için, bu satırı uygun şekilde açıklayıcı bir adla yeniden yapılandırmayı ciddi şekilde düşünmelisiniz. Yeni yöntem çağrısı, neler olduğunu açıklar. Uzun isimlerden korkmayın; Elbette sınıf / yöntem / değişken isimlerinde romanlar yazmamalısınız, fakat çok kısa ve açıklayıcı bir ismin çok kısa ve açık olmasını tercih ederim ve başlık altında bakıp ne yaptığını çözmem gerekiyor. X / y koordinatları ve yaygın olarak kullanılan kısaltmalar gibi bazı belirgin istisnalar dışında, tek karakterli adlardan ve kısaltmalardan kaçının. "BackButton" yerine "bkBtn" diye bir şey söylemek

Diliniz izin verdiği sürece, kodunuzu İngilizce bir cümle gibi okuyun. Nesneler isimleri, yöntemler fiilleri kullanır. Boolean yöntemleri tipik olarak "is" ile başlar, ancak "olabilir", "gerekir" veya "yapar" gibi kullanım durumlarına bağlı olarak, anlamını daha iyi ileten birçok seçenek vardır. Elbette, tüm diller bu konuda Smalltalk kadar iyi olamaz, ancak bazı sembollerin genellikle cümlenin parçaları olduğu anlaşılır. Şahsen mümkün olduğunca diğer dillere almak istediğim iki Smalltalk sözleşmesi, "her" ile döngü parametrelerinin adını ve koleksiyonlar için "a" (veya "bir" veya "bazı" makalelerini önekleyerek) . Bu, Java’da ortak bir standart olmayabilir ve herhangi birinin bu parçayı yoksaymasına izin verilir, ama bunun kodun okunabilirliğini büyük ölçüde artırdığını buldum. Örneğin (Java’da örnek):

public boolean shouldConsiderAbbreviating(List<String> someNames) {
  for (String eachName : someNames) {
    if (isTooLong(eachName)) {
      return true;
    }
  }
  return false;
}

Bu, biraz Java bilgisi olan insanlara aşağıdaki gibi okunabilir olmalıdır:

Bazı isimlerin (dize olan) bir listesini kısaltmayı düşünmeniz gerekip gerekmediğini belirlemek için, bazı isimler üzerinde yineleme yapın ve her isim için çok uzun olup olmadığını belirleyin; öyleyse, geri dön true; hiçbiri çok uzun değilse, geri dönün false.

Yukarıdaki kodu, sadece daha karmaşık bir yöntemde , argümanı stringsve döngü değişkenini adlandırmakla karşılaştırın string. Kullanımın adına bir bakışta açık olması yerine, farkı görmek için yakından bakmak gerekir.

İyi bir adlandırma bulmak her zaman daha fazla faktör arasında bir uzlaşmadır. Asla tam olarak tatmin olmayacaksın.

Bununla birlikte, anadiliniz böyle olmasa da, İngilizce’nin, programlama dilleri belirteçleri oluşturduğu dil olduğunu düşünün. İngilizce'ye benzeyen sözdizimini kullanmak, bir anahtar kelimeyi her bulduğunda "bozuk okuma kuralları" olmadığından kod okumayı "akıcı" hale getirir.

Genel olarak, gibi object.method(parameters)bir şema eşleştirmek gibi şeyler düşünün subject.verb(complements).

Genel programlamayı desteklemeniz gerekiyorsa kilit nokta, iyi ve tutarlı bir "fiiller" (özellikle de genel algoritmalarda kullanılması gerekenler) kümesidir.

İsimler hakkında, sınıflar neye göre are(kavram olarak) isimlendirilmeli, neye karşı isimlendirilmelidir are for.

Bu, arasında list.add(component)ve component.add_to(list)ilk tercih etti. Genel olarak "aktif geçişli" fiiller, pasif veya refleks emsallerine göre eylemleri daha iyi temsil eder. Tasarım kısıtlamadığı sürece sizi kandırır.

Yöntem adlarının uzunluğu hakkında endişelenmeyin. Yöntem adlarının yaptıklarını net bir şekilde yansıttığından emin olun. Bu başka bir şey için çok önemlidir. Yöntem adının çok uzun olduğunu düşünüyorsanız, aynı anlama gelen daha kısa bir kelime bulmak için bir eş anlamlılar sözlüğü kullanın. Örneğin Findyerine kullanın Retrieve.

Ayrıca en önemlisi, sınıflarınız için seçtiğiniz isimler. Bunlar, yöntem adlarına bakarken birçok bağlam sağlar. Bunun gibi bir yöntem imzası:

public User Find(int userId);

anlamak daha kolaydır:

public Person Find(int personId);

çünkü sınıf adından elde edilen bağlam Userprogramlayıcıya Find(), sistem kullanıcısı olan belirli bir tip insanı bulmak için olduğunu söyler . PersonSınıfı kullanan sürüm , ilk önce neden yöntemi kullanmanız gerektiğiyle ilgili size herhangi bir bağlam sağlamaz.

Platformunuzdaki diğer kişilerin bunu nasıl yaptığını inceleyin - bazı büyük oyuncuların kod stili ve adlandırma kuralları bile olabilir.

Bazı platformlar kısa isimleri tercih eder (örneğin, Win32 C API'sinde _tcsstrbir dizgede bir dize bulma işlevidir - açık değil mi?), Diğerleri okunaklı olması için kısalıkların lehine (Apple'ın Cocoa-C için Cocoa çerçevesinde) okunabilir. , bir dize içindeki bir alt dizgiyi başka bir dize ile değiştirmek ve sonucu kopya olarak adlandırmak için kullanılan yöntem stringByReplacingOccurrencesOfString: withString:). İkincisini anlaşılması oldukça kolay ve yazması oldukça zor (özellikle de kod tamamlama ile).

Kodu yazdığınızdan daha sık okuduğunuzdan (açık kaynak kitaplıklar için iki kat gerçek) ve okuma yazmaktan zordur, okuma için optimize edin. Yalnızca en son kısalık için en iyi duruma getirin ve netliği seyreltmeden mümkün olduğu kadar uzağa götürün.

1. Bu kod üzerinde çalışan her geliştirici aynı İngilizce olmayan dili konuşmayacaksa, İngilizce'yi farz edin.

2. Çalışma yaygın kuralları ve stilleri adlandırma kabul etti. Yol gösterici ilkeniz netlik olmalıdır. Stiller programlama diline göre farklılık gösterir.

3. Adınızla, kodunuzdaki çeşitli nesneler arasındaki ilişkileri anlamayı kolaylaştıracak hiçbir şey yoktur. Bunun için hala iyi yazılmış yorumlara ve belgelere ihtiyacınız var.

1. Önek kullanın. Benzer bir şeyi yapmak için bir grup yöntem kullanılmışsa veya bir şekilde gruplandırılmışsa, bu yöntemlerin ortak neye sahip olduğunu göstermek için adlarının önüne ortak bir önek koyun.
2. Başkalarının adları anında anlamalarını istiyorsanız (API adlandırmada önemli olan) net olmayan kısaltma kullanmayın.