Kodunuz hakkında profesyonel gibi nasıl yorum yapabilirsiniz: En iyi uygulama ve iyi alışkanlıklar
Kod yazma yazma yazıya çok benzer. Herkes bunu biraz farklı yapar ve bu nedenle kodumuz okunduğunda hepimizin farklı sesleri vardır. Farklı adlandırma kurallarımız ve farklı problem çözme mantığımız var. Hepimiz kodumuzun mantıklı olduğunu düşünüyoruz – özellikle başarılı olursa – diğer insanlar olmayabilir. Bunun üstesinden gelmek için, kaynak kodu hakkında yorum yapmakta hepimiz daha iyi olmalıyız. Bu şekilde, projeyi takip eden herkes, kodumuzu anlamak ve geliştirmek/geliştirmek için net bir yola sahip olacaktır. Başlamak için kodlar hakkında nasıl yorum yapılır, hepimizin yorumların ne olduğu konusunda aynı sayfada olduğumuzdan emin olalım. Bu makalede, senaryodaki satırları tartışacağız. CSS dosyasında, örneğin, okunabilecek kodun işlemci tarafından göz ardı edilen yorumlarla parçalandığı şeyler.
/** Vücut elemanı stil **/
gövde {color: kırmızı;}
H1 {boyut: 17px;}
/** Kenar çubuğu widget stil **/
#E-posta-Signup-1 {Text-Transform: Upscase;}
Her programlama dilinin kaynak kodunda yorum yapmanın farklı bir yolu vardır. PHP ve HTML ve JavaScript ve C#, kodu başlatan ve biten biraz farklı bir sembolü vardır. Bazı özel dil uygulamaları da olmasına rağmen, daha fazla paylaşılmamıştır. Bulacağınız bazı farklı yorum türlerini, kullanımlarını ve kendiniz kullanırken en iyi uygulamayı (veya belki de iyi bir alışkanlık) tartışacağız.
Kodunuz hakkında yorum yapmanın temel ilkeleri basittir:
Kısaca onlar için
Alakalı kalmalarını sağlayın
Serbestçe kullanın, ancak aşırıya kaçmayın
Hatırlayabiliyorsan, iyi olacaksın. Çatışmayı kısaca tartışmak için, rakibe yorum yapan kaynak koduna dokunalım. Kodunuz hakkında yorum yapmanın çok nadir bir fırsat olması gerektiğine inanan az sayıda geliştirici var. Bir kaynak kodu yorumuna ihtiyacınız olduğunda, kodunuzun çeşitli şekillerde zayıf olduğunun bir göstergesidir. Adı verme, mantık veya şeffaf bir şekilde yapmadığınız diğer şeylerin sözleşmesinin ve adil olmak gerekirse, bu argüman mantıklıdır. Bununla birlikte, kodunuzun ne kadar iyi yazıldığına ve hesaplandığına bakılmaksızın, belgeleri yorumlar şeklinde dahil etmek için yeterli argüman yapan bir dizi koşul vardır. Ana şey, her zaman proje üzerinde çalışan kişi olmayacaksınız ve bir sonraki kişinin ne kadar deneyimli olmasını garanti edemezsiniz. İyi bir kod yazsanız bile, karışıklık ve belirsizlik olasılığı vardır. Başlık bloğunun belgelenmesi Birkaç dosyaya bakarsanız, dolaylı kod başlar, çünkü dosyada amaç, değişkenler, işlevler, yöntemler vb. Dikkatinizi ona çekmek için etrafındaki dev kutuda bile olabilirler.
Bu iyi bir alışkanlık değil. Çünkü biraz boşuna. Aslında gerçekten işe yaramaz.
Ayrıca, yukarıdaki örneğe bakın: Çok Uzun Yorumlar Kanopisi. Çok nadiren bunu yapmak için bir neden var. O zaman yapma. Dosyaya ne girerseniz girerseniz, belgelerinize hala girilmelidir. Yorumlara sahip olmak aşırıdır. Buna ek olarak, son kullanıcı büyük olasılıkla kaynak kodunuzu asla girmeyecektir, böylece yorumlar yalnızca diğer geliştiriciler (veya belgelerini zaten bilen hardcore yazılım kullanıcıları) tarafından görülecektir. Artı, belgeler her değiştiğinde, bunu değiştirmelisiniz dosya. Bir adımı kaçırmak kolaydır ve daha sonra kod tabanınız çok kirli olabilir. Başlık yorumları yararlı olduğunda, başlık yorumları, dosyada ne beklendiğinin basit bir şekilde açıklaması için kaynak kodda kullanışlıdır. Örneğin, bu, RPG Maker adlı bir oyun geliştirme makinesi ile donatılmış bir komut dosyasıdır ve her oyun sahnesini kontrol eden çekirdek JS dosyası şöyle başlar: // ================ ============================================== ==============================
// ============================================= ==== ============================
// ============================================= ==== ============================
/**
* Oyun içindeki tüm sahnelerin üst sınıfı.
*
* @class scene_base
* @Constructors
* @aşamayı uzatır
*/
Function scene_base () {
this.initalize.Apply (bu, bağımsız değişkenler);
}
Scene_base.pototype = object.Create (stage.pototype);
Scene_base.pototype.constructors = scene_base;
Ayrıca, sürüm numarasının en üstte listelendiğini unutmayın. Bunu yap. Ancak, dosya tarihinin tam bir listesini değiştirmeyin ve yeni sürüm yayınlanır. GIT veya diğer sürüm kontrol yazılımında kaydedilir ve bu bilgiye ihtiyaç duyan herkes için kullanılabilir olmalıdır. Bu dosyayı görecek çoğu kişi için sayı sürümü yeterlidir. En yaygın kaynak yorum türünün belgeleri bir yorum hattıdır. Onlarla doğru, aşırı veya çok ekonomik yapmak arasında ince bir çizgi vardır. Bu, zaman zaman öğrenmeniz gereken bir dengedir, ancak dikkate alacak kadar iyi olan bazı pratik kurallar vardır. Bir satır yorumu yapma. Bir dizi yorum bir şeydir. Satırla satır yorumları kodun neredeyse okunamaz görünmesini sağlar. Aşağıya bakınız:
İşlev sourceCodeComment () {// bir işlev çağırıyor
var yorum = document.getElementById (“Kod yorum”). Değer; // bir değişken bildirir
if (yorum! = null && yorum! = ”) {// Bir yorum olup olmadığını değerlendirmek için bir if ifadesi başlatır
Console.log (“Yorumunuz için teşekkür ederim.”) // Konsola bir dize yazdırıyor
}
Aşırı. Gerekirse, olaydan önce veya sonra yapın. Ama her satırda değil. Bu öne çıkıyor ve genellikle yardımcı olmuyor. Hem organizasyon hem de netlik için işlev (veya öğe) öncesi bir yorum. Bundan daha fazlası belgelere girmelidir.
Belgelendirme ihtiyacını hissediyorsanız, böyle bir şey yeterlidir. //Checks bir yorum olup olmadığını görmek için. Eğer öyleyse, bir teşekkür mesajı döndürür.
Function sourceCodeComment () {
var yorum = document.getElementById (“kod yorum”). Değer; if (yorum! = null && yorum! = ”) {
Console.log (“Yorumunuz için teşekkür ederim.”)
}
Rakipler bu tür bir yorumun aşırı olduğunu söyleyecektir, çünkü adlandırma sözleşmesi işleviniz, değişkeniniz ve yönteminiz için iyidir. Bir noktada doğrudur, ancak asgari düzeyde belirsizliği korumak istiyorsanız, hızlı yorumlar bir yoldur.
Kaynak kodunun kaynağına bir uyarı vermek sorun değil, bazen bir sorun için net bir çözüm sorunu gerçekten çözmez. Bu durumda, projeye daha sonra gelişmekte olan geliştiriciler dosyaları görebilir ve net çözümde gereken yeniden düzenlemeyi düşünebilirler. Bunu yapmak zaman kaybedecek. Ya da belki gelecekte başka bir şey görünecektir ve her şeye zarar veren ve diz projesi yapan işlevleri çağırmaya çalışırlar. Bunun dışında, gerçeğin işe yaramayacağını bildiğiniz bir şey varsa ve diğer insanların gelecekte deneyeceğini biliyorsunuz, onları bu konuda uyarmak sorun değil.
// GoodCodeComment () kullanmaya çalışmayın.
// En iyi seçenek gibi görünmesine rağmen BestTPractices () ‘yi bozar.
// SimplyOKayCodeComment () INSEAD ile gittik.
SimpleOKayCodeComment () {işlevi
// Bir tür kod buraya gidiyor
}
Ayrıca, bu örnekte ne yaptığımıza dikkat ediyor musunuz? Sadece gelecekteki geliştiricilere bir uyarı vermekle kalmıyor, aynı zamanda bir işlevin ortasına bir yer tutucu yorumu da içeriyoruz. Kaynak kodu yorumları göz ardı edildiğinden, bir dosyada yer tutucu metnini depolamak için kullanabilirsiniz (oraya geri dönmek için bir tür ek açıklama veya örneğin bir açıklama olarak). Daha önce, özellikle de iyi ılımlı olmayan kaynak projede. Birisi iyi olmayan bir kod parçası bulacak ve yazarı yıkmak için bir yorum kullanacak
// işe yaramamalı, ama bir şekilde çalışıyor. İstemiyorum
// düzeltmek için hepinizin ne kadar kötü olduğunu görmenizi istiyorum.
Ya da kodu geliştirdiler, ancak kodu koydular, sadece yorum yaptı, böylece kodu gösterebilirler, önceki yazarla alay ederken. // Eski kod çok kötüydü, sadece burada bırakmam gerekiyordu .
// Düzelttim. Kodum aşağıda. Ama buna bak.
// thematrix () işlevi {
// var neo = MayBetetheone.Data + Theoracle.data
// theone ()! == neo ise
// return console.log (“Hediye aldınız, ama bir şey bekliyormuşsunuz gibi görünüyor”)
//}
Bunu asla yapmadığınızdan emin olun. Komik olduğunuzu düşünseniz bile ya da iyi görünmenizi sağlasanız bile, bu doğru değil. Kod hakkında yorum yapmanın gerçek kullanımı, kodun başka bir şey denerken yararlı kalmasıdır. Ya da daha önce başarısız olanın bir örneğini vermek için birisi artık sonuç vermeden denemedi. Kaynak Kodu Yorumları WordPress Genel olarak, WordPress dört farklı dilde çalıştırılır. HTML, CSS, PHP ve JavaScript. Yorumlar için doğru karakteri kullanmanın çok önemli olmasını sağlamak. HTML için: CSS’de:/ * Yorum kapalı olana kadar herhangi bir sayıda satır bir yorum olacaktır */Hem PHP hem de JavaScript aynı Tek ve çok menzilli yorumlar için yöntem: <? php function (); // Tek satır yorum böyle mi?
Yorum kapalı olana kadar durmayacak */ Sonuç Her gün, kod yazıyorsanız ve GitHub'a itiyorsanız, kuruluşunuzun takip etmek istedikleri yorumlar için bir stil kılavuzu olabilir. Ancak, bunu yapmazlarsa veya yalnızsanız, bunun sadece gelecekte işinizi kolaylaştırmakla kalmayacak, aynı zamanda sizi kovalayan herkese de yardımcı olacaktır. Kodunuzda yorum yapmaktan maksimum sonuç elde etmek için ipuçlarınız ve püf noktalarınız nelerdir? Makalenin Üstün Görüntüsü Skillup / Shutterstock.com
