Programlamayı düşündüğünüzde, diller, algoritmalar ve hata ayıklama gibi konulara odaklanmanız doğaldır. Ancak teknik dokümantasyon, doğru yapmak kadar önemli olabilir.
İyi belgeler olmadan kodun yeniden kullanılabilirliği zarar görebilir. Bir kod tabanında yeni olan kullanıcılar, belgeler kusursuz değilse kolayca kaybolabilir veya hüsrana uğrayabilir. Bir programın sadece ne yaptığını anlamak değil, aynı zamanda bunu nasıl ve hatta neden yaptığını anlamak da önemlidir.
Python için Pydoc ve Java için Javadoc gibi paketler, sürecin bir bölümünü otomatikleştirerek yardımcı olur. Godoc aracı Go için de aynısını yapar.
Godoc nedir?
Godoc, Go belgelerini "Gitme yolunda" oluşturmanıza, yönetmenize ve kullanmanıza izin veren bir Go paketidir. Go yolu, bir Go programcısı olarak kod kalitesini iyileştirmek için izlemeniz gereken bir dizi ilkedir.
Godoc'u kullanarak diğer geliştiricilerin belgelerini ve kodunu kolayca okuyabilirsiniz. Ayrıca kendi belgelerinizin oluşturulmasını otomatikleştirebilir ve Godoc'u kullanarak yayınlayabilirsiniz.
Godoc'a benzer Javadoc, Java için kod belgeleyici. Her ikisi de dokümantasyon oluşturmak için modüllerdeki yorumları ve kodu kullanır. Ve her iki araç da bu belgeleri HTML olarak yapılandırır, böylece bir tarayıcıda görüntüleyebilirsiniz.
Godoc'a Başlarken
Godoc'u kullanmak kolaydır. Başlamak için, bu komutu kullanarak golang web sitesinden Godoc paketini kurun:
Git golang.org/x/tools/cmd/godoc'u edinin
Bu komutu çalıştırmak Godoc'u belirttiğiniz çalışma alanına kuracaktır. Tamamlandığında, çalıştırabilmeniz gerekir tanrı öğretisi bir terminalde komut. Kurulumunuzla ilgili herhangi bir hata varsa, Go'yu yeni bir sürüme güncellemeyi deneyin.
Godoc, oluşturduğu belgelere dahil etmek için tek ve çok satırlı yorumları arar.
Kodu, Go yolunda açıklandığı gibi biçimlendirdiğinizden emin olun. Etkili Git yayını En iyi sonuçlar için Go ekibi tarafından.
İşte C++ tarzı tek satırlı yorumların kullanıldığı bir örnek:
// Kullanıcı, aşağıdakileri içeren bir yapı modelidir:
tip kullanıcı yapı {
}
C tarzı blok yorumlarını da kullanabilirsiniz:
/*
Kullanıcı özel bir veri yapısıdırBuraya herhangi bir metin ekleyebilirsiniz ve Godoc sunucusu, çalıştırdığınızda onu biçimlendirir.
*/
tip kullanıcı yapı {
}
Yukarıdaki yorumlarda, yorum User struct'ın ne yaptığını anlattığı için cümlelere “User” başlamaktadır. Bu, Go yolunun tartıştığı birçok konudan biridir. Belge cümleleri, paket listesinde ilk cümle göründüğünden, yararlı bir adla başlamak çok önemlidir.
Godoc Sunucusu Çalıştırmak
Kodunuzu yorumladıktan sonra çalıştırabilirsiniz. tanrı öğretisi projenizin kod dizininden terminalinizde komut.
Geleneksel olarak, Go geliştiricileri bağlantı noktası kullanır 6060 belgeleri barındırmak için. Bu bağlantı noktasında bir Godoc sunucusu çalıştırma komutu şudur:
ilahi -http=:6060
Yukarıdaki komut, kod belgelerinizi yerel ana bilgisayar veya 127.0.0.1. Bağlantı noktasının 6060 olması gerekmez; Godoc, kullanılmayan herhangi bir bağlantı noktasında çalışır. Ancak, Go dokümantasyon kurallarına uymak her zaman en iyisidir.
Komutu çalıştırdıktan sonra, ziyaret ederek belgelerinizi bir tarayıcıda görüntüleyebilirsiniz. yerel ana bilgisayar: 6060. Godoc'un belgelerinizi oluşturması için gereken süre, boyutuna ve karmaşıklığına bağlı olacaktır.
Aşağıdaki kod, bu durumda tek satırlık yorumlar kullanılarak Git yoluna bağlıdır.
// paketin adı
paket kullanıcı// fmt biçimlendirmeden sorumludur
içe aktarmak (
"fmt"
)// Kullanıcı, insan verilerinin bir yapısıdır
tip kullanıcı yapı {
Yaş int
İsim sicim
}işlevana() {
// insan, Kullanıcı yapısının bir başlatmasıdır
insan := Kullanıcı {
Yaş: 0,
İsim: "kişi",
}fmt. Println (insan. Konuşmak())
}
// Talk, User yapısının bir metodudur.
işlev(alıcı Kullanıcı)Konuşmak()sicim {
dönüş "Her Kullanıcı Bir Şey Söyleyecek!"
}
Godoc'u yukarıdaki kod modülünde çalıştırırsanız, şöyle bir çıktı görmelisiniz:
Go resmi dokümantasyon web sitesinde bulacağınıza benzer, tanıdık bir biçimde olduğuna dikkat edin.
Godoc, paket bildiriminden önceki yorumu şu şekilde kullanır: genel bakış. Bu yorumun programınızın ne yaptığını açıkladığından emin olun.
bu dizin hızlı bir şekilde gezinebilmeniz için tür bildirimlerine ve yöntemlere bağlantılar içerir.
Godoc ayrıca, paketi oluşturan kaynak kodunu Paket dosyaları bölüm.
Godoc Kullanarak Belgelerinizi Geliştirme
Godoc belgelerinize düz metinden fazlasını dahil edebilirsiniz. Godoc'un bağlantı oluşturacağı URL'ler ekleyebilir ve yorumlarınızı paragraflar halinde yapılandırabilirsiniz.
Bir kaynağa bağlantı vermek istiyorsanız, yorumunuza URL'yi yazın, Godoc onu tanıyacak ve bir bağlantı ekleyecektir. Paragraflar için boş bir yorum satırı bırakın.
// Paket ana
paket ana// Belge, normal bir belgeyi temsil eder.
//
// Bağlamak https://google.com
tip belge yapı {
sayfalar int
Referanslar sicim
imzalı bool
}// Write, depoya yeni bir Belge yazar
//
// Yazmayı Wikipedia.com'dan öğrenebilirsiniz.
işlevYazmak() {
}
Godoc'un, onları bağlamak için URL'leri tam olarak yazmanızı gerektirdiğini unutmayın. Bu örnekte, Google URL'si şunları içerir: https:// önek, bu nedenle Godoc ona bir bağlantı ekler. Wikipedia alanı kendi başına tam bir URL olmadığı için Godoc onu olduğu gibi bırakacaktır.
Go kodunuzu belgelerken uygulayabileceğiniz en iyi ilkelerden bazıları şunlardır:
- Belgelerinizi basit ve özlü tutun.
- Adlarına göre işlevler, türler ve değişken bildirimleri cümlesini başlatın.
- Kod olarak önceden biçimlendirmek için girintili bir satır başlatın.
- "HATA(ad)" ile başlayan "HATA(joe): Bu işe yaramaz" gibi yorumlar özeldir. Godoc bunları hata olarak tanıyacak ve belgelerin kendi bölümlerinde rapor edecektir.
Godoc Belgeleme Sorunlarınızı Hafifletebilir
Godoc'u kullanarak daha üretken olabilir ve programlarınızı elle belgeleme çabası konusunda daha az endişe duyabilirsiniz.
Belgelerinizi kesin, ayrıntılı ve hedef kitlenizin okumasını ve anlamasını kolaylaştıracak noktaya kadar tutmalısınız. Programınızı değiştirirken kod yorumlarını güncel tutmanız da çok önemlidir.
Godoc'u kullanma hakkında daha fazla bilgi edinmek için Godoc paketi belgelerine bakın.