Kodunuzu Bir Profesyonel Gibi Nasıl Yorumlayabilirsiniz: En İyi Uygulamalar ve İyi Alışkanlıklar

Kod yazmak nesir yazmaya çok benzer. Her insan bunu biraz farklı yapar ve bu nedenle kodumuz okunduğunda hepimizin farklı bir sesi olur. Farklı adlandırma kurallarımız ve farklı problem çözme mantığımız var. Hepimiz kodumuzun mantıklı olduğunu düşünüyoruz – özellikle işe yarıyorsa – ama başka biri olmayabilir. Bununla mücadele etmek için hepimizin kaynak kod yorumlarında daha iyi olmamız gerekiyor. Bu şekilde, projeye kim gelirse gelsin, kodumuzu anlamak ve iyileştirmek/düzeltmek için net bir yola sahip olacaktır.

Kod Nasıl Yorumlanır – Temel Bilgiler

Başlangıç ​​olarak, yorumların ne olduğu konusunda hepimizin aynı sayfada olduğundan emin olalım. Bu makalede, komut dosyalarının kendi içindeki satır içi yorumları tartışacağız. Örneğin, okunabilir kodun işlemciler tarafından göz ardı edilen yorumlarla bölündüğü bir CSS dosyasında bunun gibi şeyler.

/** Body Element Styling **/

body {color:red;}

h1 {size:17px;}


/** Sidebar Widget Styling**/

#email-signup-1 {text-transform:uppercase;}

Her programlama dilinin kaynak kodunda farklı bir yorum yapma şekli vardır. PHP ve HTML ile JavaScript ve C#'ın tümü, kodu başlatan ve bitiren biraz farklı sembollere sahiptir. Dile özgü bazı uygulamalar da olsa da, paylaşılanlardan çok daha fazlası var.

Karşılaşacağınız farklı yorum türlerinden bazılarını, bunların kullanımlarını ve en iyi uygulamaları (veya belki de yalnızca edinebileceğiniz iyi alışkanlıkları) kendiniz kullanırken tartışacağız.

Kodunuzu yorumlamanın temel ilkeleri basittir:

• Onları kısa yap
• Onları alakalı tutun
• Onları özgürce kullanın, ancak aşırıya kaçmayın

Bunları aklında tutabilirsen, gayet iyi gidiyor olacaksın.

Muhalifleri Tartışacak Bir An

Çok kısaca, karşı çıkanları yorumlayan kaynak koduna değinelim. Kodunuzu yorumlamanın son derece nadir bir durum olması gerektiğine inanan küçük olmayan bir geliştirici alt kümesi vardır. Kaynak kodu yorumlarına ihtiyacınız olduğunda, bu, kodunuzun bir şekilde zayıf olduğunun bir göstergesidir. Adlandırma kurallarınız, mantığınız veya başka bir şey olması gerektiği kadar şeffaf değil.

Ve adil olmak gerekirse, bu argüman belirli bir anlam ifade ediyor. Bununla birlikte, kodunuz ne kadar iyi yazılmış ve faktörlü olursa olsun, belgeleri yorum biçiminde eklemek için fazlasıyla argüman oluşturan bir dizi koşul vardır.

Birincil olanlar, her zaman proje üzerinde çalışan siz olmayacaksınız ve bir sonraki kişinin ne kadar deneyimli olacağını garanti edemezsiniz. Harika kod yazsanız bile, kafa karışıklığı ve belirsizlik olasılığı vardır.

Başlık Bloğu Belgeleri

Bazı dosyalara bakarsanız, kod hemen başlamaz çünkü dosyada amacının ne olduğunu, değişkenleri, işlevleri, yöntemleri vb. açıklayan büyük bir başlık vardır. Dikkatinizi çekmek için etrafındaki dev bir kutuda bile olabilirler.

Bu, içine girmek için iyi bir alışkanlık değil. Çünkü biraz anlamsız. Şey, aslında çok anlamsız.

Ayrıca yukarıdaki örneğe bakın: yorum başlığı çok uzun. Bunu yapmak için çok nadir nedenler vardır. Yapma.

O dosyaya koyacağınız her şey yine de belgelerinize eklenmelidir . Bir yorumda olması gereksizdir. Ek olarak, son kullanıcı muhtemelen kaynak kodunuza asla girmeyecektir, bu nedenle yorum yalnızca diğer geliştiriciler (veya yazılımın zaten belgeleri bilen hardcore kullanıcıları) tarafından görülecektir.

Ayrıca, belgeler ne zaman değişse, o dosyada değiştirmeniz gerekir. Bir adımı kaçırmak kolaydır ve ardından kod tabanınız ciddi şekilde bozulabilir.

Başlık Yorumları Faydalı Olduğunda

Başlık yorumları, o dosyada ne bekleneceğine ilişkin basit açıklamalar için kaynak kodda kullanışlıdır. Örneğin, bu, RPG Maker adlı bir oyun geliştirme motoruyla birlikte gelen bir komut dosyasıdır ve her oyun sahnesini kontrol eden çekirdek JS dosyası şöyle başlar:

//=============================================================================
// rpg_scenes.js v1.6.2
//=============================================================================

//=============================================================================

/**
 * The Superclass of all scenes within the game.
 * 
 * @class Scene_Base
 * @constructor 
 * @extends Stage
 */
function Scene_Base() {
    this.initialize.apply(this, arguments);
}

Scene_Base.prototype = Object.create(Stage.prototype);
Scene_Base.prototype.constructor = Scene_Base;

Ayrıca, sürüm numarasının en üstte listelendiğini unutmayın. Bunu yap. Ancak, dosyanın değiştirildiği ve yeni sürümlerin yayınlandığı tarihlerin kapsamlı bir listesini vermeyin. Bu, Git'te veya başka bir sürüm kontrol yazılımında kaydedilir ve bu bilgiye ihtiyaç duyan herkes tarafından kullanılabilir olmalıdır. Sürüm numarası, bu dosyaya bakan çoğu kişi için yeterlidir.

Hat İçi Belgeler

En yaygın kaynak kodu yorumu türü, satır içi yorumdur. Doğru yapmak, aşırıya kaçmak veya onlara karşı çok tutumlu olmak arasında ince bir çizgi vardır. Bu, zaman içinde öğrenmeniz gereken bir denge, ancak dikkate almanız gereken oldukça iyi kurallar var.

Satır satır yorum yapmayın. Satır içi yorum bir şeydir. Satır satır yorum, kodun neredeyse okunamaz görünmesini sağlar. Aşağıya bakınız:

function sourceCodeComment () { //calls a function
  var comment = document.getElementbyID("Code Comment").value; // declares a variable
  if (comment != null && comment != '') {  //starts an if statement to evaluate if there's a comment
        return console.log("Thank you for your comment.") //prints a string to the console
}

Bu aşırı. Gerekirse, işlevden önce veya sonra yapın. Ama her satırda değil. Rahatsız edici ve genellikle yararsızdır. İşlevden (veya öğeden) önce bir yorum, organizasyon ve netlik için iyidir. Bundan daha fazlası belgelere girmelidir.

Belgelemenin gerekli olduğunu düşünüyorsanız, bunun gibi bir şey yeterli olacaktır.

//checks to see if there's a comment. If so, returns a thank you message.

function sourceCodeComment () {
  var comment = document.getElementbyID("Code Comment").value; 
  if (comment != null && comment != '') { 
        return console.log("Thank you for your comment.")
}

Hayır diyenler, bu tür yorumların bile gereksiz olduğunu söyleyecektir çünkü işlevleriniz, değişkenleriniz ve yöntemleriniz için iyi adlandırma kuralları kodu okunabilir hale getirecektir. Bu bir noktaya kadar doğrudur, ancak belirsizliği mutlak minimumda tutmak istiyorsanız, hızlı bir yorum yapmanın yolu budur.

Kaynak Kodu Yorumlarına Uyarı Yazmak Sorun Değildir

Bazen bir sorunun bariz çözümü aslında sorunu çözmez. Bu durumlarda, geliştirme aşamasında bir projeye daha sonra gelen geliştiriciler, bir dosyaya bakabilir ve bu bariz çözümde yeniden düzenlemeyi düşünebilir. Bunu yapmak tamamen zaman kaybı olacaktır.

Ya da belki ileride başka bir şey ortaya çıkar ve her şeyi kıran ve projeyi dize getiren bir fonksiyon çağırmaya çalışırlar.

Ne olursa olsun, işe yaramayacağını bildiğiniz bir şey varsa ve başkalarının gelecekte deneyeceğini bildiğiniz bir şey varsa, onları bu konuda uyarmanızda bir sakınca yoktur.

// Don't bother trying to use goodCodeComment() here. 
// It breaks bestPractices() despite seeming like the best option.
// We went with simplyOkayCodeComment() instead.

function simpleOkayCodeComment() {
	//some kind of code goes here
}

Ayrıca, bu örnekte ne yaptığımızı fark ettiniz mi? Sadece gelecekteki geliştiricilere uyarı vermekle kalmadık, bir fonksiyonun ortasına yer tutucu bir yorum ekledik. Kaynak kodu yorumları yok sayıldığından, bunları dosyada yer tutucu metni tutmak için kullanabilirsiniz (oraya geri dönmek için kendinize bir açıklama olarak veya açıklama olarak birisine örnek olarak).

pislik olma

Bunun daha önce olduğunu gördüm, özellikle de çok iyi yönetilmeyen açık kaynaklı projelerde. Birisi, yıldızdan daha az bir kod parçacığı bulacak ve yazarı olumsuzlamak için bir yorum kullanacak.

//This function looks like it was written by a third grader.
//It shouldn't work, but it does somehow. I don't want
//to fix it because I want you all to see how bad it is.

Ya da belki kodu düzeltirler, ancak kodu eklerler, basitçe yorumlanırlar, böylece kodlarını gösterebilirler ve aynı zamanda önceki yazarla alay ederler.

//The old code was so bad, I just had to leave it here for you to see.
//I fixed it. My code is below. But look at this.

// function theMatrix() {
//	var neo = maybeTheOne.data + theOracle.data
//	if theOne() !== neo
//		return console.log("you got the gift, but it looks like you're waiting for something")
// }

Sadece bunu asla yapmadığınızdan emin olun. Komik olduğunu ya da bunun seni iyi gösterdiğini düşünsen bile, öyle değil ve değil.

Kodu yorumlamanın gerçek kullanımı, başka bir şey denerken bu kodu elinizin altında tutmanızdır. Ya da daha önce neyin işe yaramadığına bir örnek vermek gerekirse, birileri tekrar denemesin, sonuçsuz.

WordPress için Kaynak Kodu Yorumları

Genel olarak, WordPress dört farklı dilde çalıştırılır. HTML, CSS, PHP ve JavaScript. Yorumlar için doğru karakterlerin kullanıldığından emin olmak zorunludur.

HTML için:

<!-- comments go here and can be single or on multiple lines --></em>

CSS'de:

/* Any number of lines will be a comment until the comment is closed */ 

Hem PHP hem de JavaScript, tek ve çok satırlı yorumlar yapmak için aynı yöntemlere sahiptir:

<?php function(); // a single line comment is like this ?>

veya

<?php /* unlike above, you can carriage return
				and no matter how many lines you use,
					the comment won't stop until closed */

Çözüm

Her gün siperlerdeyseniz, kod yazıyorsanız ve GitHub'a gönderiyorsanız, kuruluşunuzun takip etmenizi istedikleri yorumlar için bir stil kılavuzu olabilir. Ancak, yapmazlarsa veya tek başınızaysanız, bunları aklınızda bulundurmanız yalnızca gelecekte işinizi kolaylaştırmakla kalmayacak, aynı zamanda sizden sonra gelen herkese de yardımcı olacaktır.

Kodunuza yorum yapmaktan en iyi şekilde yararlanmak için ipuçlarınız ve püf noktalarınız nelerdir?

Makale özellikli görsel Skillup / Shutterstock.com