การใส่ Comment ใน JavaScript (แบบ Workๆ)

Comment เป็นสิ่งหนึ่งที่มีความสำคัญมากในการเขียนโปรแกรม เพราะเป็นสิ่งที่ช่วยอธิบาย Code ของเราว่าทำงานอย่างไรเพราะเมื่อเวลาผ่านไปเป็นเวลานานหรือมี Dev คนอื่นนำ Code ไปพัฒนาต่อเจ้า Comment นี้แหละจะเป็นตัวช่วยให้เราอ่าน Code ได้เข้าใจมากขึ้น(ดีกว่าไปนั่งแกะผิดแกะถูก)วันนี้ผมมีตัวอย่าง Comment ในแต่ละงานมาให้รองพิจารณาดูนะครับ เพื่อนๆอ่านแล้วคงสงสัยนะครับว่ามันจำเป็นถึงขนาดต้อง Comment เป็นงานๆ เลยเหรอสำหรับภาษาอื่นๆ แล้วไม่จำเป็นครับแต่สำหรับ JavaScript ค่อนข้างจำเป็นครับเพราะ JavaScript ไม่มีการระบุชนิดตัวแปลเหมือนภาษาอื่น(ยกตัวอย่าง เช่น var X; เราก็ไม่รู้ว่า X เป็นตัวแปลชนิดไหน แต่ภาษาอื่นสามารถระบุชนิดตัวแปลได้เช่น Bool X; หรือ String X; เราก็สามารถที่จะรู้ได้ว่าต้องการให้ X เป็นตัวแปรชนิดไหน) เราอาจไม่ต้องทำตามทั้งหมดแต่เราก็เลือกเอาแต่สิ่งที่ดูแล้วน่าจะเป็นประโยชน์มากที่สุดไปนะครับ เรามาลองดูกัน

Basic Comment

//  สำหรับ  one-line comment

/* ………. */ สำหรับ multi-line comment

Comment สำหรับ Function มาตรฐาน

ตัวอย่างการ Comment สำหรับ Function ทั่วไป

Type1

  /**
         * Steps from the current point in the presentation to the
         * slide which matches the specified horizontal and vertical
         * indices.
         *
         * @param {int} h Horizontal index of the target slide
         * @param {int} v Vertical index of the target slide
         * @param {int} f Optional index of a fragment within the
         * target slide to activate
         * @param {int} o Optional origin for use in multimaster environments
         */
        function slide( h, v, f, o ) {}

Type2

/**
 * make() returns a new element
 * based on the passed in tag name
 *
 * @param <String> tag
 * @return <Element> element
 */
function make(tag) {

  // ...stuff...

  return element;
}

Comment สำหรับ  License

อันนี้ใช้สำหรับใบอนุญาตถูกต้องตามกฎหมายหรือข้อความลิขสิทธิ์

Type1

/*!
 * javascriptthai.js
 * http://www.javascriptthai,com/javascriptthai-js
 * MIT licensed
 *
 * Copyright (C) 2013 JAVA El LAB, http://javascript.se
 */

Type2

/**
 * @preserve Copyright 2009 SomeThirdParty.
 * Here is the full license text and copyright
 * notice for this file. Note that the notice can span several
 * lines and is only terminated by the closing star and slash:
 */

Type3

/*!
 * javascriptthai JavaScript Library v4.9.1
 * http://www.javascriptthai.com/
 *
 * Includes Sizzle.js
 * http://sizzlejs.com/
 *
 * Copyright 2005, 2012 JavaScriptthai Foundation, Inc. and other contributors
 * Released under the MIT license
 * http://www.javascriptthai.com/license
 *
 * Date: 2013-1-1
 */

 

Comment สำหรับบอกว่าเป็น constructor

ตัวอย่างการ Comment Function constructor

/**
 * A rectangle.
 * @constructor
 */
function GM_Rect() {
  ...
}

Comment สำหรับ Parameter ต่างๆ

ตัวอย่างการ Comment ค่า Parameter เพื่ออธิบายค่าต่างๆ

//-- UTM User Settings
var _ufsc=1;			// set client info flag (1=on|0=off)
var _udn="auto";		// (auto|none|domain) set the domain name for cookies
var _uhash="on";		// (on|off) unique domain hash for cookies
var _utimeout="1800";   	// set the inactive session timeout in seconds
var _ugifpath="/__utm.gif";	// set the web path to the __utm.gif file
var _utsp="|";			// transaction field separator
var _uflash=1;			// set flash version detect option (1=on|0=off)
var _utitle=1;			// set the document title detect option (1=on|0=off)
var _ulink=0;			// enable linker functionality (1=on|0=off)
var _uanchor=0;			// enable use of anchors for campaign (1=on|0=off)
var _utcp="/";			// the cookie path for tracking
var _usample=100;		// The sampling % of visitors to track (1-100).

Comment สำหรับการ Return ค่า

ตัวอย่างการ Comment ค่า Return ของ Function เพื่ออธิบายค่าต่างๆ

 /**
         * Returns an object describing the available fragment
         * directions.
         *
         * @return {Object} two boolean properties: prev/next
         */
        function availableFragments() {}

 

Comment อื่นๆ

/*

	JavaScript.Sys : 1.3
	------------------------------------------------------------
	Peacock:  “Instruments to perform color-music: Two centuries of technological experimentation,” Leonardo, 2        1 (1988), 397-406.
	Gerstner:  Karl Gerstner, The Forms of Color 1986
	Klein:  Colour-Music: The art of light, London: Crosby Lockwood and Son, 1927.
	Jameson:  “Visual music in a visual programming language,” IEEE Symposium on Visual Languages, 1999, 111-11        8. 
	Helmholtz:  Treatise on Physiological Optics, New York: Dover Books, 1962 
	Jones:  The art of light & color, New York: Van Nostrand Reinhold, 1972
	------------------------------------------------------------
	Reference: http://www.javascriptthai.com

*/

 

……

หวังว่าคงจะมีประโยชน์บ้างครับ

Leave a Reply