Dokümantasyon da Neymiş?

Son zamanlarda sektörde öncü gelen yazılımcılardan çok sık duyar oldum neymiş her proje dokümante edilmeliymiş.

Genel argüman ise dokümante edilmeyen projelerin anlaşılması, sonraki yazılımcılar için önemliymiş ayrıca genel olarak tüm ekibin projede neler yapacağını, neler yaptığını vs. bildirmesi açısından da önemliymiş.

Yazılımcı dediğin yazılan kodu çalışmasa bile anlar. Doküman falan yazılımcının doğasına ters.

Evet evet bu yukarıdakileri, 3–4 ≥ yıllık geliştiriciden duydum. Ben yazarken zorlandım ama o düşünürken zorlanmıyor. Ayrıca dokümantasyon işlemini Yeni Word Belgesi.docx olarak düşünülüyor olabilir. Bu yanılgıyı bir kenara bırakırsak eğer şu tarz basit bir dokümantasyon çok önemli olabilir.

/// <summary>
/// iki sayıyı toplayıp, integer döndüren bir method<typeparamref name=”int”/>
/// </summary>
/// <typeparam name=”int”>int türünden bir method</typeparam>
public static int toplam(int n)
{
return n + 5;
}

Over architecture olmadığı sürece dokümante etmek en iyi şeydir. Çünkü muhtemelen bir şeyler yanlış gidecek ya da yeni featurelar eklenmek istenecek. Sizden sonra gelen bir geliştirici ya da sizinle beraber o projede görev alan geliştirici de bir şeyleri merak edip oraya bakıyor olabilir.

C# gibi dillerin kendilerine has IDE’leri olduğu için şanslısınız gerçi artık editörler diğer dillere de böyle destekler vermekte. Ancak olmadığı durumlarda türün ne olduğunu göremediğinize yani işiniz tam bir sıkıntı.

Dokümana İhtiyacınız Yok, Kodunuz Dokümanınız Olsun

Örneğin bir JavaScript library yazıyorsunuz hiçbir metod açıklayıcı değil ve mutlak int türünden değer alması gereken bir de fonksiyona sahipsiniz. Editörünüz tam teşekküllü bir IDE fakat o bile ne değer aldığını bildirmiyor. Örnek:

function birSeyler(birDeger) {
return birDeger + 5;
}

Yukarıdaki fonksiyonun ne değer alacağını IDE’niz tamamını taramadıkça bilemez. Bilmek zorundalığı da yok aslında. Programcı böyle bir fonksiyonun ne alacağını kestiremez. Adına baksanıza. Malumunuz ülkemizde yasin_kac() fonksiyonuna muş cevabını verenler var. Gelin bu fonksiyonu şöyle değiştirelim:

/**
* Hüseyin: Topluyorum burada haberin olsun
*
* @see [Github]{@link https://github.com}
* @param {Number} birDeger - Bu sayısal bir değer olsun ona göre
* @returns {Number} - Bu sayısal bir değer dönmek zorunda ona göre
*/
function birSeyler(birDeger) {
return birDeger + 5;
}

Demem o ki dokümantasyon da neymiş. Bas geç metodolojisi bizim için çok daha değerli arkadaşlar. Böyle projelere karşı bazen şirketlerin agresif tutumlarından kaynaklı söz geçiremediğiniz durumlar oluyor.

Hatta sizden daha bilgisiz, daha niteliksiz kişilerden emir aldığınız dahi olabilir. Fakat siz bu alışkanlığa bir kere sahip olursanız gittiğiniz her büyük şirkette ortama adapte olabilirsiniz.

Bu arada şu fonksiyona da doküman yazmayın bir zahmet:

function alertVer(mesaj) {
alert(mesaj)
}

Son olarak sevdiğim bir sözle kapatayım:

Comment Your Fucking Code!