Jadi ini solusi sementara? Kemudian gunakan nama yang disarankan oleh peninjau, tetapi tandai metode ini sebagai usang, sehingga menggunakannya akan menghasilkan peringatan setiap kali seseorang menyusun kode.
Jika tidak, Anda mungkin selalu mengatakan bahwa itu 216147
tidak masuk akal dalam kode, karena kode tersebut tidak ditautkan ke sistem pelacakan bug (ini lebih merupakan sistem pelacakan bug yang ditautkan dengan kontrol sumber). Kode sumber bukan tempat yang baik untuk referensi tiket bug dan versi, dan jika Anda benar-benar perlu meletakkan referensi itu di sana, lakukan di komentar.
Perhatikan bahwa bahkan dalam komentar, jumlah bug saja tidak terlalu berharga. Bayangkan komentar berikut:
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.
}
Bayangkan bahwa kode itu ditulis sepuluh tahun yang lalu, bahwa Anda baru saja bergabung dengan proyek, dan ketika Anda bertanya di mana Anda dapat menemukan informasi tentang bug 8247, kolega Anda mengatakan bahwa ada daftar bug di situs web dari melaporkan perangkat lunak sistem, tetapi situs web itu direnovasi lima tahun yang lalu, dan daftar bug baru memiliki nomor yang berbeda.
Kesimpulan: Anda tidak tahu tentang apa bug ini.
Kode yang sama bisa ditulis dengan cara yang sedikit berbeda:
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.
}
Sekarang Anda mendapatkan pandangan yang jelas tentang masalah ini. Meskipun tampaknya tautan hiperteks di akhir komentar sudah mati lima tahun yang lalu, itu tidak masalah, karena Anda masih dapat memahami mengapa FindReportsByDate
digantikan oleh FindReportsByDateOnly
.