Kaynak Kod Yorum Styling İpuçları ve En İyi Uygulamalar

Büyük projelere zaman ayırmış olan geliştiriciler kod yorumlarının önemini anlamaktadır. Aynı uygulamaya birçok özellik kazandırırken işler karmaşıklaşmaya meyillidir. Fonksiyonlar, değişken referanslar, dönüş değerleri, parametreler dahil olmak üzere çok fazla veri biti var.?

Hem solo hem de takım projeleri olarak, kodunuzu yorumlamanızın esastır olması şaşırtıcı değildir. Ancak birçok geliştirici bu sürece nasıl devam edeceğinin farkında değil. Bazı kişisel numaralarımın ana hatlarını temiz, biçimlendirilmiş kod yorumları oluşturma. Standartlar ve yorum şablonları, geliştiriciler arasında farklılık gösterecektir - ancak sonuç olarak temiz ve okunabilir yorumlar kodunuzdaki kafa karıştırıcı alanları daha fazla açıklamak için.

Yorum formatlamadaki farklılıklardan bazılarını tartışmaya başlamalıyız. Bu size proje koduyla ne kadar ayrıntılı olabileceğiniz konusunda daha iyi bir fikir verecektir. Daha sonra hemen kullanmaya başlayabileceğiniz bazı ipuçları ve örnekler sunacağım.!

Yorum Stilleri: Genel Bakış

Sunulan bu fikirlerin sadece kılavuzlar daha temiz yorumlara doğru. Tek tek programlama dilleri, belgelerinizin nasıl kurulacağına ilişkin kılavuz ilkeler veya spesifikasyonlar getirmemiştir..

Olduğu söyleniyor, günümüz geliştiricileri kendi kod yorumlama sistemlerini biçimlendirmek için birlikte gruplandılar. Birkaç ana akım stil sunacağım ve amaçlarının ayrıntılarına gireceğim.

Satır İçi Yorumlama

Pratik olarak her bir programlama dili sunar satır içi yorumlar. Bunlar tek satırlık içerikle sınırlıdır ve metni yalnızca belirli bir noktadan sonra yorumluyor. Mesela C / C ++ 'da bunun gibi bir satır içi yorumu başlatırsınız:

// değişken listelemeye başla var myvar = 1;… 

Bu, birkaç saniye boyunca koda girmek için mükemmeldir. kafa karıştırıcı işlevselliği açıklayabilir. Çok fazla parametre veya işlev çağrısı ile çalışıyorsanız, yakınlarda çok sayıda satır içi yorum yapabilirsiniz. Ancak en faydalı kullanım bir küçük işlevsellik için basit fikirli açıklama.

if (callAjax ($ params)) // callAjax'ı başarıyla kullanıcı parametreleriyle çalıştırın… code

Her şeyden önce, kodun açılış braketinden sonra yeni bir satırda olması gerekir. Aksi halde hepsi aynı yorum satırında yakalanır.! Denize düşmekten kaçının genellikle sayfanızın başından sonuna kadar tek satırlık yorumlar görmeniz gerekmediğinden, özellikle de kodunuzdaki kavşakların karışması için, bunların son dakikada düşürülmesi daha kolaydır.

Tanımlayıcı Bloklar

Büyük bir açıklama eklemeniz gerektiğinde, genellikle tek bir astar işe yaramaz. Programlamanın her alanında kullanılan önceden biçimlendirilmiş yorum şablonları vardır. Açıklayıcı bloklar en çok işlevler ve kütüphane dosyaları etrafında görülür. Ne zaman yeni bir fonksiyon ayarladığınızda bildirimin üstüne açıklayıcı bir blok ekle.

/ ** * @desc, bir iletiyi görüntülemek için bir kalıcı pencere açar * @param dizesi $ msg - görüntülenecek ileti * @return bool - başarı veya başarısızlık * / function modalPopup ($ msg) … 

Yukarıda, açıklayıcı bir fonksiyon yorumuna basit bir örnek verilmiştir. Muhtemelen JavaScript denilen bir fonksiyon yazdım. modalPopup tek bir parametre alır. Yukarıdaki yorumlarda, her satırın bir önceliğe sahip olduğu phpDocumentor'a benzer bir sözdizimi kullandım. @ simgesine, ardından seçilen bir tuşa basın. Bunlar kodunuzu hiçbir şekilde etkilemeyeceğinden, yazabilmeniz için @açıklama yerine @desc hiçbir değişiklik yapmadan.

Bu küçük tuşlar aslında denir yorum etiketleri web sitesinde yoğun olarak belgelenmiştir. Kendinizinkini oluşturmaktan ve bunları kodunuz boyunca istediğiniz gibi kullanmaktan çekinmeyin. Her şeyin akmasını sağlamaya yardımcı olduklarını biliyorum. Önemli bilgileri bir bakışta kontrol edebilirim. Ayrıca kullandığımı da fark etmelisin. / * * / blok tarzı yorum formatı. Bu her şeyi koruyacak daha temiz Her satıra bir çift eğik çizgi eklemek yerine.

Grup / Sınıf Yorumları

İşlevlerin ve döngülerin yorumlanmasının yanı sıra, blok alanları da bu kadar sık ​​kullanılmamaktadır. Gerçekten güçlü gereken yer yorumları engelle arka uç belgelerinizin veya kütüphane dosyalarının başında bulunur. Web sitenizdeki her dosya için eksiksiz bir dokümantasyon yazmak ve sağlam belgeler yazmak kolaydır - bu uygulamayı WordPress gibi birçok CMS'de görebiliriz..

Sayfanızın en üst alanı, dosyanın kendisiyle ilgili yorumlarda bulunmalıdır. Bu şekilde yapabilirsiniz nerede düzenleme yaptığınızı hızlıca kontrol edin Aynı anda birden fazla sayfa üzerinde çalışırken. Ek olarak bu alanı kullanabilirsiniz. İhtiyacınız olan en önemli fonksiyonlar için bir veritabanı sınıf dışı.

/ ** * @desc bu sınıf kullanıcı etkileşimi için işlevleri tutacaktır * örnekler arasında user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @required settings.php * / soyut sınıf myWebClass  

Gördüğün gibi, sahte için sadece küçük bir örnek sınıf kullandım. myWebClass kodu. Bazı meta bilgileri ekledim irtibat için benim adım ve e-posta adresim ile. Geliştiriciler açık kaynak kod yazarken, bu genellikle iyi bir uygulamadır; bu nedenle diğerleri destek için sizinle iletişime geçebilir. Bu, daha büyük geliştirme ekiplerinde çalışırken sağlam bir yöntemdir..

Etiket @gereklidir başka yerlerde kullandığım bir şey değil. Projelerimden birkaçında formatı takip ettim, sadece birçok yöntemi kişiselleştirdiğim sayfalarda. Sayfaları bir dosyaya eklediğinizde, herhangi bir kod çıkarmadan önce gelmeleri gerekir. Bu yüzden ana sınıf yorum bloğuna bu detayları eklemek iyi bir yoldur. hangi dosyaların gerekli olduğunu hatırlayın.

Ön uç Kod Yorumlama

Şimdi 3 önemli yorum şablonunu ele aldığımızda, diğer birkaç örneğe bakalım. Statik HTML'den jQuery ve CSS koduna geçen birçok geliştirici var. HTML yorumları, programlama uygulamalarına göre daha amaçlı değildir, ancak stil kitaplıkları ve sayfa komut dosyaları yazarken işler zaman içinde karışık olabilir.

JavaScript, Java, PHP ve C / C'ye benzer daha geleneksel bir yorum yöntemi izler++. CSS sadece eğik çizgi ve yıldız işareti ile tanımlanan blok tarzı yorumları kullanır. Ne CSS ne de JS sunucu tarafında ayrıştırıldığı için yorumlarınızın ziyaretçilerinize açıkça gösterileceğini hatırlamalısınız, ancak bu yöntemlerden herhangi biri kodunuzda geri dönmek için bilgilendirici tidbit'ler bırakmak için harika çalışır.

Özellikle CSS dosyalarını parçalamak bir angarya olabilir. Internet Explorer veya Safari için bir düzeltmeyi açıklamak için satır içi yorum bırakmaya hepimiz aşinayız. Ancak CSS yorumlamanın jQuery düzeyinde kullanılabileceğine ve PHP'nin bunları kullandığına inanıyorum. Kod yorumlamasıyla ilgili bazı ayrıntılı ipuçlarına dokunmadan önce stil grupları oluşturmaya başlayalım..

CSS Stil Grupları

Yıllardır CSS tasarlayanlar için neredeyse ikinci bir doğa olarak geliyor. Tüm özellikleri, sözdizimini yavaşça ezberler ve stil sayfaları için kendi sisteminizi kurarsınız. Kendi çalışmamla aradığım şeyi yarattım. gruplama benzer CSS bloklarını bir alana eşleştirmek.

CSS düzenlemeye geri döndüğümde, birkaç saniyede ihtiyacım olanı kolayca bulabilirim. Stilleri gruplama şekliniz tamamen size kalmış ve bu sistemin güzelliği. Aşağıda ana hatlarıyla açıkladığım birkaç standart var:

• @resets - varsayılan tarayıcı kenar boşluklarını, dolguyu, yazı tiplerini, renkleri vb..
• @fonts - paragraflar, başlıklar, blok alıntılar, bağlantılar, kod
• @ navigasyon - ana çekirdek web sitesi gezinme bağlantıları
• @layout - sarıcı, konteyner, kenar çubukları
• @header & @footer - bunlar tasarımınıza bağlı olarak değişebilir. Olası stiller arasında bağlantılar ve sıralanmamış listeler, altbilgi sütunları, başlıklar, alt geziler bulunur

Stil sayfalarını gruplandırırken etiketleme sistemi çok yardımcı olabilir. Ancak PHP veya JavaScript'ten farklı olarak tek bir @group etiketini bir kategori veya anahtar kelimeler izler. Aşağıdaki 2 örneği ekledim, böylece ne demek istediğimi anlayabiliyorsun..

/ ** @group altbilgi * / #footer styles…

/ ** @group altbilgi, küçük yazı tipleri, sütunlar, dış bağlantılar ** / 

Alternatif olarak, her yorum bloğuna biraz daha fazla ayrıntı ekleyebilirsiniz. Ben seçerim işleri basit ve anlaşılır kılmak bu yüzden stil sayfalarının gözden kaybolması kolaydır. Yorum yazmanın tümüyle anlaşılması şartıyla belgelerle ilgilidir.!

Daha İyi Yorum Yapmak İçin 4 İpucu

Bu makalenin ilk yarısını kod yorumlama için çeşitli biçimlere bakarak harcadık. Şimdi kodunuzu temiz, düzenli ve anlaşılması kolay tutmak için bazı genel ipuçlarını tartışalım.

1. Her şeyi Okunabilir Tutun

Bazen geliştiriciler olarak bunu unuturuz İnsanların okuması için yorumlar yazıyoruz. Anladığımız tüm programlama dilleri makineler için üretilmiştir, bu nedenle düz yazılı metne dönüştürmek sıkıcı olabilir. Üniversite düzeyinde bir araştırma makalesi yazmak için burada olmadığımızı not etmek önemlidir, ancak sadece ipucu bırakarak!

işlevi getTheMail () // burada kod, eğer özel sendMyMail () işlev çağrısı gerçek döndürürse, e-posta / * çalıştırma kodu oluşturacaktır, eğer /libs/mailer.class.php içindeki kullanıcının senden tüm alanları doldurup doldurmadığını kontrol ederiz ve mesaj gönderildi! * / if (sendMyMail ()) true; // doğru tutun ve ekrandaki başarıyı görüntüleyin

Sadece bir kaç kelime bile hiç yoktan iyidir. Düzenleme yapmak ve gelecekteki projeler üzerinde çalışmak için geri döndüğünüzde, genellikle ne kadar unutacağınız şaşırtıcı olacaktır. Her gün aynı değişkenlere ve işlev adlarına bakmadığınızdan, kodunuzun çoğunluğunu yavaşça unutabilirsiniz. Böylece yapabilirsiniz asla çok fazla yorum bırakma! Ama çok fazla kötü yorum bırakabilirsin.

Genel bir kural olarak, duraklama ve yazmadan önce yansıtmak için biraz zaman ayırın. Kendine sor program hakkında en kafa karıştırıcı olan şey ve Bunu en iyi nasıl açıklayabilirsin “kukla” dil? Ayrıca düşünün kodu neden aynen yazıyorsun?.

Özel olarak oluşturulmuş (veya 3. taraf) işlevlerin amacını unuttuğunuzda en kafa karıştırıcı hatalardan bazıları ortaya çıkıyor. Birkaç başka dosyaya geri giden bir yorum izi bırak bu, işlevselliği daha kolay hatırlamanıza yardımcı olacaksa.

2. biraz boşluk hafifletmek!

Ne kadar önemli olduğunu yeterince stres edemem Beyaz boşluk olabilir. Bu gider iki kat doğru yüzlerce dosya içeren büyük web sitelerinde çalışan PHP ve Ruby geliştiricileri için. Bütün gün bu koda bakıyor olacaksınız! Sadece önemli alanlara göz atsanız harika olmaz mıydı??

$ dir1 = "/ home /"; // ana ev dizinini ayarla $ myCurrentDir = getCurDirr (); // geçerli kullanıcı dizinini ayarla $ userVar = $ get_username (); // mevcut kullanıcının kullanıcı adı

Yukarıdaki örnekte, her satırdaki yorumlar ve kodların arasına yerleştirdiğim ekstra dolguyu göreceksiniz. Dosyalar arasında gezinirken, bu yorum tarzı açıkça göze çarpıyor. O hata bulma ve kodunuzu yüzlerce kez düzeltmeyi kolaylaştırır değişken bloklar böyle olduğunda temiz.

Nasıl çalıştığı konusunda kafanız karışan bir fonksiyonun içindeki kod üzerinde benzer bir görev gerçekleştirebilirsiniz, ancak bu yöntem sonunda kodunuzu satır içi yorumlar ile karıştırır ve bu tam tersi! Bu senaryoda tavsiye ederim mantık alanı etrafında geniş bir blok satırı yorumu eklemek.

$ (document) .ready (function () $ ('. sub'). hide (); // pageload'da alt gezinmeyi gizle / ** .itm div içindeki bir çapadaki bir click olayını denetle eylem, sayfanın tıklandığında değişmemesi için .itm öğesinin ana öğesine, ardından açık / kapalı ** / $ ('. itm a') geçişine geçmek için bir sonraki .sub listesi. ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('fast');););

Bu, alt menü kaydırma gezinmesini hedef alan küçük bir miktar jQuery kodudur. İlk yorum neden bütün bunları sakladığımızı açıklamak için satır içi. .alt sınıflar. Canlı tıklama etkinliği işleyicisinin üstünde, bir blok yorumu kullandım ve tüm yazıyı aynı noktaya getirdi. Bu, işleri paragraftan ziyade daha güzel hale getirir - özellikle yorumlarınızı okuyanlar için.

3. Kod Yazarken Yorum Yapın

Düzgün aralıklarla birlikte bu, içine girmenin en iyi alışkanlıklarından biri olabilir. Kimse çalıştıktan sonra programlarına geri dönmek ve her parçayı belgelemek istemez. Birçoğumuz geri dönüp kafa karıştırıcı alanları belgelemek istemiyoruz! Gerçekten çok çalışıyor.

Ancak kod yazarken yorumları yazabilirsiniz. aklında her şey hala taze olacak. Genellikle geliştiriciler bir sorunla karşılaşırlar ve en kolay çözüm için web'i tararlar. Eureka anına çarptığınızda ve böyle bir sorunu çözdüğünüzde genellikle önceki hatalarınızı anladığınız netlikte bir an vardır. Bu olurdu en iyi zaman kodunuz hakkında açık ve dürüst yorumlar bırakmak için.

Ek olarak, bu size tüm dosyalarınızı yorumlamaya alışmak için pratik sağlayacaktır. Fonksiyonu zaten oluşturduktan sonra geri dönüp bir şeyin nasıl çalıştığını anlamak için gereken zaman miktarı. Hem gelecekteki benliğiniz hem de takım arkadaşlarınız, önceden yorum bıraktığınız için teşekkür eder..

4. Buggy Hataları ile Mücadele

Hepimiz bilgisayar başında saatlerce kod yazarak oturamayız. Sanırım deneyebiliriz, ama bir noktada uyumak zorundayız! Bazı özelliklerin hala bozuk olduğu gün için kodunuzla yolunuzu ayırmanız gerekebilir. Bu senaryoda, sizin için çok önemlidir işleri bıraktığınız yer hakkında uzun ve ayrıntılı yorumlar bırakın.

Taze bir gece uykusundan sonra bile, kodlamanın hızına geri dönmenin ne kadar zor olabileceğine şaşırabilirsiniz. Örneğin, bir resim yükleme sayfası oluşturuyorsanız ve onu tamamlanmamış bırakmak zorunda kalırsanız, Süreçte bıraktığınız yer hakkında yorum yapmalı. Görüntüler yükleniyor ve geçici bellekte saklanıyor mu? Ya da belki yükleme formunda bile tanınmıyorlar ya da yükleme sonrasında sayfada düzgün bir şekilde görüntülenmiyorlar..

Hataları yorumlamak iki ana sebepten dolayı önemlidir. İlk önce bıraktığınız yeri kolayca kaldırın ve problemi çözmek için tekrar aklımda bulunmayı deneyin. İkincisi, yapabilirsin. web sitenizin canlı üretim sürümü ile test alanı arasında bir ayrım yapın. Unutmayın ki yorumlar neden bir şey yaptığını açıkla, tam olarak ne yaptığını değil.

Sonuç

Web uygulamaları ve yazılım geliştirme, zor bir uygulama olsa da tatmin edici bir uygulamadır. Yazılım oluşturma işlemini gerçekten anlayan birkaç geliştiriciden biriyseniz, kodlama becerilerinizi geliştirmek önemlidir.. Açıklayıcı yorumlardan çıkmak, uzun vadede sadece iyi bir uygulamadır, ve muhtemelen pişman olmayacaksınız!

Daha net kod yorumlaması için önerileriniz varsa, aşağıdaki tartışma alanında bize bildirin!