Geçici bir geçici çözüm için bir yöntem adına bir hata numarası eklemek kötü uygulama olarak mı kabul edilir?

Üst düzey bir adam olan iş arkadaşım beni bir kod incelemesinde engelliyor, çünkü 'PerformSqlClient216147Workaround' adlı bir yöntemi belirtmemi istiyor çünkü bazı hatalar için geçici bir çözüm ###. Şimdi, yöntem adı önerim, yöntemin gerçekte ne yaptığını açıklamaya meyilli olan PerformRightExpressionCast gibi bir şey. Argümanları şu çizgi üzerinde ilerliyor: "Peki, bu yöntem yalnızca bu dava için geçici bir çözüm olarak ve başka hiçbir yerde kullanılmıyor."

Geçici bir geçici çözüm için yöntem adının içine hata numarası eklenmesi kötü uygulama olarak kabul edilir mi?

İş arkadaşınızın önerdiği gibi bu yöntemi adlandırmam. Yöntem adı, yöntemin ne yaptığını belirtmelidir. Gibi bir isim PerformSqlClient216147Workaroundne yaptığını göstermez. Bir şey varsa, bunun bir geçici çözüm olduğunu belirtmek için yöntemi tanımlayan yorumları kullanın. Bu aşağıdaki gibi görünebilir:

/**
 * Cast given right-hand SQL expression.
 *
 * Note: This is a workaround for an SQL client defect (#216147).
 */
public void CastRightExpression(SqlExpression rightExpression)
{
    ...
}

MainMa ile hata / hata numaralarının kaynak kodun kendisinde görünmemesi gerektiği, bunun yerine kaynak kod yorumlarında kaynak kod yorumlarında yer alması gerektiğine katılıyorum , ancak kaynak kod yorumlarında görünmeleri korkunç değil. Hata / kusur numaraları asla yöntem adlarında kullanılmamalıdır.

Hiçbir şey işe yarayan geçici bir düzeltmeden daha kalıcı değildir.

Önerisi 10 yıl içinde iyi görünüyor mu? Her bir değişikliği düzeltdiği kusur ile yorumlamak yaygın bir pratikti. Daha yakın zamanlarda (son 3 yılda olduğu gibi), bu tarz yorumlama kod korumanın azaltılması olarak yaygın bir şekilde kabul edilmektedir - ve bu, yalnızca yorumlarla, yöntem adlarıyla değil.

Teklif ettiği şey sizin QC ve QA sistemlerinizin önemli ölçüde eksik olduğunun kanıtıdır. Hataların ve hata düzeltmelerinin izlenmesi, kaynak koduna değil, hata izleme sistemine aittir. Kaynak kod değişikliklerinin izlenmesi kaynak kontrol sistemine aittir. Bu sistemler arasındaki çapraz referanslama, hataların kaynak koduna göre izlenmesini sağlar.

Kaynak kodu bugün için, bugün değil, yarın için değil (gelecek yıl ne yapmayı planladığınızı kaynağa yazmazsınız) ...

Yani bu geçici bir çözüm mü? Ardından, gözden geçiren tarafından önerilen adı kullanın, ancak yöntemi geçersiz olarak işaretleyin, böylece birisinin kodu her kullanışında bir uyarı vermesi gerekir.

Değilse 216147, kodun hata izleme sistemine bağlı olmadığından (kodun kaynak kontrolüne bağlı olan hata izleme sistemi olduğundan) kodda anlam ifade etmeyeceğini her zaman söyleyebilirsiniz . Kaynak kodu, hata biletlerine ve sürümlerine yapılan referanslar için iyi bir yer değildir ve bu referansları gerçekten oraya koymanız gerekirse, yorumlarda yapın.

Yorumlarda bile hata sayısının tek başına çok değerli olmadığını unutmayın. Aşağıdaki yorumu hayal edin:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The following method replaces FindReportByDate, because of the bug 8247 in the
    // reporting system.
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

Kodun on yıl önce yazıldığını, projeye yeni katıldığınızı ve 8247 numaralı hata ile ilgili herhangi bir bilgiyi nerede bulabileceğinizi sorduğunuzu, iş arkadaşlarınızın web sitesinde bir hata listesi olduğunu söylediğini hayal edin. raporlama sistemi yazılımı, ancak web sitesi beş yıl önce yeniden yapıldı ve yeni hatalar listesi farklı numaralara sahip.

Sonuç: Bu hatanın ne hakkında olduğu hakkında hiçbir fikriniz yok.

Aynı kod biraz farklı bir şekilde yazılmış olabilir:

public IEnumerable<Report> FindReportsByDateOnly(DateTime date)
{
    // The reporting system we actually use is buggy when it comes to searching for a report
    // when the DateTime contains not only a date, but also a time.
    // For example, if looking for reports from `new DateTime(2011, 6, 9)` (June 9th, 2011)
    // gives three reports, searching for reports from `new DateTime(2011, 6, 9, 8, 32, 0)`
    // (June 9th, 2011, 8:32 AM) would always return an empty set (instead of isolating the
    // date part, or at least be kind and throw an exception).
    // See also: http://example.com/support/reporting-software/bug/8247
    var dateOnly = new DateTime(date.Year, date.Month, date.Day);
    return this.FindReportsByDate(dateOnly);
}

private IEnumerable<Report> FindReportsByDate(DateTime date)
{
    Contract.Requires(date.Hour == 0);
    Contract.Requires(date.Minute == 0);
    Contract.Requires(date.Second == 0);

    // TODO: Do the actual work.
}

Şimdi konuyla ilgili net bir görüş elde edersiniz. Yorumun sonundaki köprü metni bağlantısının beş yıl önce öldüğü görülse bile, bunun neden FindReportsByDatedeğiştirildiğini hala anlayabildiğiniz için farketmez FindReportsByDateOnly.

PerformSqlClient216147WorkaroundO zaman daha bilgilendirici buluyorum PerformRightExpressionCast. İşlev adına, ne yaptığına, neden yaptığına ya da bu konuda nasıl daha fazla bilgi alacağına dair hiçbir şüphe yoktur. Kaynak kodda arama yapmak çok kolay olacak açık bir işlevdir.

Sayıyı düzelten bir hata izleme sistemi ile sorunu benzersiz bir şekilde tanımlar ve sistemde bu hatayı gördüğünüzde ihtiyacınız olan tüm ayrıntıları sağlar. Bu, kaynak kodda yapılması çok akıllıca bir şey ve neden bir değişiklik yapıldığını anlamaya çalışırken gelecekteki geliştiricilere zaman kazandıracak.

Eğer kaynak kodunuz varsa bu fonksiyon adlarından birçoğunu görürseniz, sorun sizin adlandırma kuralınız değildir. Sorun şu ki, buggy yazılımın var.

İş arkadaşınızın önerisinde değer var; Koddaki değişiklikleri, bu veritabanında bulunan hata veritabanında belirtilen nedenlerle, değişikliğin neden yapıldığıyla ilişkilendirerek izlenebilirlik sağlar.

Ancak, bu fonksiyonun var olmasının tek sebebinin böcek üzerinde çalışmak olduğunu da öne sürüyor. Sorun bir sorun olmasaydı, yazılımın o şeyi yapmasını istemezdiniz. Muhtemelen , yazılımın işini yapmasını istersiniz, bu nedenle işlevin adı ne yaptığını ve neden sorun alanının neden yapılmasını gerektirdiğini açıklamalıdır; neden hata veritabanının buna ihtiyacı var. Çözüm, bir yara bandı gibi değil uygulamanın bir parçası gibi görünmelidir.

Bence ikimiz de o şeyi orantılı olarak aldınız.

Teknik argümanınıza katılıyorum, ancak günün sonunda, birkaç gün / hafta / ay içinde kod tabanından kaldırılabilecek geçici bir düzeltme olması durumunda, o kadar fark yaratmayacak.

Bence egonu tekrar kutusuna koyup kendi yolunu bulsun. (Eğer o da dinliyorsa, sizden ödün vermeniz gerektiğini söylerdim. Her iki ego da kutularına geri döndü.)

Her halükarda, sen ve o yapacak daha iyi şeyleriniz var.

Geçici bir geçici çözüm için yöntem adının içine hata numarası eklenmesi kötü uygulama olarak kabul edilir mi?

Evet.

İdeal olarak, sınıfınız, uygulama akışınızdaki / durumunuzdaki bir konsepti haritalandırmak / uygulamak için en iyi harita olmalıdır. Bu sınıfın API'lerinin adları, sınıfın durumuna ne yaptığını yansıtmalıdır, böylece müşteri kodu bu sınıfı kolayca kullanabilir (yani, özellikle okumadığınız sürece kelimenin tam anlamıyla bir şey ifade etmeyen bir isim belirtmeyin).

Bu sınıfın genel API'sinin bir kısmı temel olarak "belge / konum X'de açıklanan Y işlemini gerçekleştir" diyorsa, diğer kişilerin API'yi anlama yeteneği aşağıdakilere bağlı olacaktır:

1. harici belgelerde ne arayacaklarını bilerek

2. harici belgelerin nereye bakılacağını bilerek

3. zaman ve emek harcayarak gerçekten bakıyorlar.

Sonra tekrar, yöntem adınız bile "X konumunun" bu kusur için nerede olduğunu söylemiyor.

Sadece (herhangi bir sebep olmadan gerçekçi bir şekilde) koda erişimi olan herkesin, aynı zamanda kusur izleme sistemine erişimi olduğunu ve izleme sisteminin kararlı kodun etrafında olacağı sürece devam edeceğini varsayar.

En azından, kusurun her zaman aynı yerde erişilebilir olacağını ve bunun değişmeyeceğini biliyorsanız (son 15 yıldır aynı URL’de olan bir Microsoft arıza numarası gibi), API belgelerinde sorun.

Buna rağmen, bir sınıfın API'sinden daha fazlasını etkileyen diğer hatalar için geçici çözümler olabilir. Sonra ne yapacaksın?

Birden fazla sınıfta aynı kusur numarasına sahip API'lere sahip olmak ( data = controller.get227726FormattedData(); view.set227726FormattedData(data);size gerçekten çok fazla şey söylemez ve yalnızca kodu daha belirsiz hale getirir.

Ameliyattan (tanımlayıcı adlarını kullanarak diğer tüm kusurları çözülür karar verebilir data = controller.getEscapedAndFormattedData(); view.setEscapedAndFormattedData(data);"az surprize" tasarım prensibi kırar senin 216.147 kusur durumunda (hariç) - veya isterseniz bu şekilde koymak, bunu kodunuzun "WTFs / LOC" ölçümünü arttırır).

TL; DR: Kötü uygulama! Odana git!

Bir programcının ana hedefleri çalışma kodu ve ifadenin açıklığı olmalıdır.

Geçici çözüm yöntemini adlandırma (.... Geçici çözüm). Bu hedefe ulaşmak gibi görünüyor. Umarım, bir aşamada temel sorun giderilir ve geçici çözüm yöntemi kaldırılır.

Bana göre, bir hatanın ardından bir yöntemin adlandırılması, hatanın çözülmediğini veya kök nedenin tanımlanmadığını gösterir. Başka bir deyişle, hala bilinmeyen bir şey olduğunu gösteriyor. Üçüncü taraf bir sistemde bir hata üzerinde çalışıyorsanız, çözümünüz çözümdür çünkü nedeni siz bilirsiniz - düzeltemezler veya düzeltemezler.

SqlClient ile etkileşimin bir parçası, doğru bir ifade dökümü gerçekleştirmenizi gerektiriyorsa, kodunuz "performRightExpressionCast ()" yazmalıdır. Nedenini açıklamak için kodu her zaman yorumlayabilirsiniz.

Geçtiğimiz 4 buçuk yıl boyunca yazılımı sürdürdüm. Zıplarken kodun kafasını karıştırmayı kafa karıştırıcı yapan şeylerden biri, yalnızca tarihe bağlı olduğu şekilde yazılmış koddur. Başka bir deyişle, bugün yazılmış olsaydı işe yaramadı. Ben kaliteden değil, bir bakış açısına değiniyorum.

Bir meslektaşım bir keresinde “Bir hatayı düzeltirken kodu olması gerektiği gibi yapın” dedi. Tercümanlık şekli "Kodu, bu hata hiç bulunmamışsa nasıl göründüğüne göre değiştir" şeklindedir.

sonuçlar:

1. Genellikle, sonuç olarak daha az kod.
2. Basit kod
3. Kaynak kodundaki hatalara daha az referans
4. Gelecekteki gerileme riski daha azdır (kod değişikliği tamamen doğrulandıktan sonra)
5. Analiz etmek daha kolaydır, çünkü geliştiricilerin artık alakalı olmayan öğrenme geçmişi ile kendilerini zorlamaları gerekmez.

Kaynak kodunun bana şu anki durumuna nasıl geldiğini anlatması gerekmez. Sürüm kontrolü bana geçmişi söyleyebilir. Kaynak kodunu sadece çalışmak için gereken durumda olması gerekiyor. Bununla birlikte, ara sıra "// bug 12345" yorumu fena bir fikir değil, ancak kötüye kullanıyor.

Bu nedenle, 'PerformSqlClient216147Workaround' yönteminizi adlandırıp adlandırmamaya karar verirken, kendinize şu soruları sorun:

1. Kodu yazmadan önce 216147 numaralı hatayı bilseydim, nasıl halledebilirdim?
2. Geçici çözüm nedir? Eğer bu kodu daha önce hiç görmemiş biri ona bakarsa, onu takip edebilecekler mi? Bu kodun nasıl çalıştığını bilmek için hata takip sisteminin kontrol edilmesi gerekli midir?
3. Bu kod ne kadar geçici? Deneyimlerime göre @mattnz'ın belirttiği gibi geçici çözümler genellikle kalıcı hale geliyor.