En İyi Uygulamalarım – Genel
1. Yorumlar – hem nimet hem külfet
İyi yorum yazmak bir sanattır. Özenle yazılırsa bir nimet, çoğu zaman ise boşa zahmet.
Kendini belgeleyen kod (self-documenting code) “hiç yorum yok” demek değildir. Kod, nasıl sorusunu mümkün olduğunca kendisi ifade etmelidir; yorumlar ise neden sorusunu, açık olmayan kısıtları ve bir API’nin sözleşmesini tamamlar.
Aşağıda kendini belgeleyen kod ile iyi ve kötü yorumlara dair bazı örnekler var.
Sık duyulan bir argüman, yorumların kolayca güncelliğini yitirdiğidir. Oysa aynı sorun değişken ve metot adları için de geçerlidir!
Eyvah – bunu asla yapmayın:
int age = 32; // set the value of the age integer to 32
Kendini belgeleyen kod: Anlamlı değişken adları işin yarısıdır
Kötü:
var dateTime = DateTimeUtil.getNow();
İyi:
var now = DateTimeUtil.getNow();
Bir örnek daha:
Kötü:
User user = this.getBruce();
Kötü:
// testing user without permission
User user = this.getBruce();
İyi:
User userWithoutPermission = this.getBruce();
Kendini belgeleyen kod: Anlamlı metot adları
Kötü:
public String sanitizeInput(String input) {
// replace underscore with spaces
return input.replaceAll("_", " ");
}
İyi:
public String replaceUnderscoreWithSpaces(String input) {
return input.replaceAll("_", " ");
}
Kendini belgeleyen kod: Private metotlar
Kötü: Metot, okuyucuyu doğrulamayı, hesaplamayı ve iş kuralını aynı anda çözmeye zorluyor.
public Invoice createInvoice(Order order, Customer customer) {
if (order.items().isEmpty()) {
throw new IllegalArgumentException("Order needs at least one item");
}
BigDecimal subtotal = order.items().stream()
.map(item -> item.unitPrice().multiply(BigDecimal.valueOf(item.quantity())))
.reduce(BigDecimal.ZERO, BigDecimal::add);
BigDecimal discount = customer.isPremium()
? subtotal.multiply(new BigDecimal("0.10"))
: BigDecimal.ZERO;
return new Invoice(order.id(), subtotal, discount, subtotal.subtract(discount));
}
İyi: Public metot akışı anlatıyor. Private ve stateless metotlar tek tek niyetleri adlandırıyor ve bağımlılıklarını parametreler ile dönüş değerleri üzerinden görünür kılıyor.
public Invoice createInvoice(Order order, Customer customer) {
requireItems(order);
BigDecimal subtotal = calculateSubtotal(order.items());
BigDecimal discount = loyaltyDiscountFor(customer, subtotal);
return invoiceFor(order, subtotal, discount);
}
private static void requireItems(Order order) {
if (order.items().isEmpty()) {
throw new IllegalArgumentException("Order needs at least one item");
}
}
private static BigDecimal calculateSubtotal(List<OrderItem> items) {
return items.stream()
.map(item -> item.unitPrice().multiply(BigDecimal.valueOf(item.quantity())))
.reduce(BigDecimal.ZERO, BigDecimal::add);
}
private static BigDecimal loyaltyDiscountFor(Customer customer, BigDecimal subtotal) {
return customer.isPremium()
? subtotal.multiply(new BigDecimal("0.10"))
: BigDecimal.ZERO;
}
private static Invoice invoiceFor(
Order order,
BigDecimal subtotal,
BigDecimal discount
) {
return new Invoice(order.id(), subtotal, discount, subtotal.subtract(discount));
}
Her satırın kendi metoduna ihtiyacı yoktur. Çıkarılan şey, kesin bir isim verilebilen bütünlüklü bir düşüncedir. processData() ya da handleStuff() gibi isimler ise hiçbir şey kazandırmaz.
Temel kural: Ne olduğunu değil, neden olduğunu yorumlayın
Burada ne olduğu açık:
public Duration retryDelay(int retryCount) {
long seconds = Math.min(1L << retryCount, 60);
return Duration.ofSeconds(seconds);
}
Peki neden oluyor?
Daha iyisi:
public Duration retryDelay(int retryCount) {
// Cap the delay so an outage never blocks queued jobs for more than one minute.
long seconds = Math.min(1L << retryCount, 60);
return Duration.ofSeconds(seconds);
}
Gerçek hayattan bir örnek daha. Ajax yükleme göstergesini (spinner) gösterip gizleyen metotlar görüyoruz. Ancak dört metot var. Nedeni ilk bakışta pek anlaşılmıyor:
function showAjaxLoader() {
$('.layout-ajax-loader').children().first().show();
}
function hideAjaxLoader() {
$('.layout-ajax-loader').children().first().hide();
}
function suppressAjaxLoader() {
getOnlyElementByClassOrNull('layout-ajax-loader').style.display = 'none';
}
function releaseAjaxLoader() {
getOnlyElementByClassOrNull('layout-ajax-loader').style.display = '';
}
Metotların hepsi birbirine çok benziyor ve bir şekilde görünürlüğü CSS üzerinden değiştiriyor gibi. Kısa bir yorumla kullanım amaçları hemen netleşiyor:
showAjaxLoader: function() {
$('.layout-ajax-loader').children().first().show();
},
hideAjaxLoader: function() {
$('.layout-ajax-loader').children().first().hide();
},
// take the control from primefaces and don't allow the spinner to show, no matter what
suppressAjaxLoader: function() {
getOnlyElementByClassOrNull('layout-ajax-loader').style.display = 'none';
},
// reset the state after hiding, to give the control back to primefaces
releaseAjaxLoader: function() {
getOnlyElementByClassOrNull('layout-ajax-loader').style.display = '';
},
Bir örnek daha:
Kötü:
/**
* Sets the tool tip text.
*
* @param text the text of the tool tip
*/
public void setToolTipText(String text) {}
İyi:
/**
* Registers the text to display in a tool tip. The text
* displays when the cursor lingers over the component.
*
* @param text the string to display. If the text is null,
* the tool tip is turned off for this component.
*/
public void setToolTipText(String text) {}
21.06.2021 tarihli atölye çalışmasındaki tartışma: Geliştiricilerin ortak görüşü, Javadoc’tan genel olarak kaçınılması gerektiğiydi (parametre kâbusu, sürekli güncelliğini yitiriyor ve bakımı zahmetli); yalnızca bir parametre gerçekten ek açıklama gerektiriyorsa ya da aksi hâlde uzun metodun tamamını okumak gerekecekse kullanılmalı.
Temel kuralın istisnası: Ne olduğunu yorumlayın – burada tavsiye edilir
Kod aksi hâlde anlaşılır olmayacağı için okunabilirliği belirgin biçimde kolaylaştırıyorsa:
let isAlwaysAllowedKey = (
e.which === 8 || /* BACKSPACE */
e.which === 35 || /* END */
e.which === 36 || /* HOME */
e.which === 37 || /* LEFT */
e.which === 38 || /* UP */
e.which === 39 || /* RIGHT*/
e.which === 40 || /* DOWN */
e.which === 46 || /* DEL*/
e.ctrlKey === true && e.which === 65 || /* CTRL + A */
e.ctrlKey === true && e.which === 88 || /* CTRL + X */
e.ctrlKey === true && e.which === 67 || /* CTRL + C */
e.ctrlKey === true && e.which === 90 /* CTRL + Z */
)
Yorumlar – Linux çekirdeğinin kodundaki küfürler
Son olarak Linux çekirdeğinden eğlenceli bir anekdot – kaynak koddaki tüm küfürlerin sayısı:
https://www.vidarholen.net/contents/wordcount/#fuck*,shit*,damn*,idiot*,retard*
Yorum yazarken iyi eğlenceler!
2. Büyük program rutinlerindeki private metotlar tehlikelidir
Dikkat! Günümüzün nesne yönelimli dünyasında her zaman çok sayıda private metot bulunur. Bu normalde sorun değildir. Sorun, bu metotlar alanlara, yani state’e, erişmeye başladığında ve büyük rutinlerin içinde yer aldığında ortaya çıkar. Bu tür alt metotlar private ve stateless olmalıdır. Aksi takdirde tek başlarına çağrıldıklarında çoğu zaman başa dert açarlar. Geliştiriciler eninde sonunda alt metodu doğrudan çağırmayı akıl edecektir. Geçersiz state’ler, hataların başlıca nedenlerinden biridir. Bu konuda, John Carmack’in (id Software, Doom) bazı görüşlerini ve kodun son derece kararlı olması gereken uygulamalarda (ör. uzay uçuşu) alt rutinlerin çoğu zaman yasaklandığını, bunun da kodu daha deterministik kıldığını anlatan ilginç bir makale: http://number-none.com/blow/john_carmack_on_inlined_code.html
Bu anekdot, modern ve stateless Java/Spring dünyasına ancak kısmen uyarlanabilir, ama yine de düşündürücü bir fikir.