Java Dokümantasyon Hazırlama Rehberi
Popüler Kültür’de Dokümantasyonun yeri.
İlla ki karşılaşmışsınızdır “vay efendim dokümantasyonsuz koda dokunmam” , “dokümantasyonsuz proje, haritasız vadiye benzer” ve benzeri bir çok mizanseni görüyoruz. Bugün, hem bize hem de ardımıza nasıl kod yazdığımızın rehberini oluşturmayı öğreniceğiz.
Nedir Dokümantasyon ?
Kısaca Projemiz içerisinde ki her bir partikülün (Method, Class, Field, Return Type, Exception vb.) O proje için ne anlam ifade ettiğini, neden var olduğunu ve nasıl çalıştığınızı açıkladığımız kısımdır.
Bunun önemi küçümsenmeyecek kadar büyük. Bazen yazdığınız bir kodun üzerinden aylar, belki yıllar geçtikten sonra orada o methodun ne yaptığını hatırlayamıyor, ya da çözemiyor olabilirsiniz. Bir başka senaryo ise, projeden ayrıldınız ve yerinize başka bir developer geldi, bu meslektaşınıza yol göstermek hepimizin boynunun borcudur :)
örneğin, aşağıda gördüğünüz görsel, bir Doc örneğidir.
Dokümantasyonun Parçaları Nelerdir ?
Description : Methodun en temel açıklamasının, yani işlevinin açıklandığı kısımdır. Bu kısıma methodun ne iş yaptığını, ve nasıl yaptığını açıklamak gerekiyor.
Param : Parametre kısımıdır. bu noktada bu method içerisinde kullanılan parametrelerin tipi, ve işlevi yazılmalıdır.
Throws : Bu methodun çalışması esnasında, eğer Exception fırlatacak bir senaryosu varsa, bu noktada belirtilmelidir, örneğimizde “eğer uygulama başlayamazsa”, bir exception fırlatacağı yer alıyor.
Return : Methodun, hangi veri tipinde ve nihayetinde hangi datayı return edeceğinin belirtildiği kısımdır.
See : Eğer methodun bir overloading versiyonu var ise, burada belirtilir. “hani bak ben bunu yazdım da, şu şu parametrelerle çalışan versiyonu da var bi bak istersen” anlamı taşıdığını söyleyebiliriz.
Basit düzeyde bu kadar Parametresini bilmek yeterli olacaktır.
Nasıl Java Doc Oluşturabiliriz ?
Çok Basit ! Yazdığınız Methodun hemen üzerine gelerek “ /** ” karakterlerinden sonra Enter tuşuna basarak Taslak oluşturabilirsiniz.
TEBRİKLER ! artık “ yahu bu kod ne yapıyordu ? bunu neden yazmışım ? gibi kendinize sorular sormanıza gerek kalmayacak 🥳”
Eğer Bu kadarı sizi kesmediyse Sizi JAVA DOC HTML RENDER Konulu Yazımıza Davet Edelim efendim..
Herkese iyi çalışmalar..
