diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 9aa51eb64..0adb7e6bc 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -1,38 +1,38 @@ -# ความคิดเห็น (Comments) +# คอมเมนต์ -อย่างที่เรารู้จากบท ความคิดเห็นสามารถเป็นบรรทัดเดียว: เริ่มต้นด้วย `//` และหลายบรรทัด: `/* ... */` +ดังที่เราได้เรียนรู้จากบท แล้วว่า คอมเมนต์สามารถเป็นบรรทัดเดียว: เริ่มต้นด้วย `//` หรือหลายบรรทัด: `/* ... */` -โดยปกติเราใช้ความคิดเห็นเพื่ออธิบายว่าโค้ดทำงานอย่างไรและทำไม +โดยปกติเราใช้คอมเมนต์เพื่ออธิบายว่าโค้ดทำงานอย่างไรและทำไมถึงทำงานแบบนั้น -ที่แรกเห็น การใส่ความคิดเห็นอาจดูชัดเจน แต่มือใหม่ในการเขียนโปรแกรมมักใช้มันผิดๆ +ในทีแรกการเขียนคอมเมนต์อาจดูเป็นเรื่องง่าย แต่มือใหม่ในการเขียนโปรแกรมมักใช้คอมเมนต์ในทางที่ผิด -## ความคิดเห็นแย่ๆ +## คอมเมนต์ที่ไม่ดี -มือใหม่มักจะใช้ความคิดเห็นเพื่ออธิบาย "ว่าอะไรกำลังเกิดขึ้นในโค้ด" แบบนี้: +มือใหม่มักใช้คอมเมนต์เพื่ออธิบาย "สิ่งที่กำลังเกิดขึ้นในโค้ด" แบบนี้: ```js -// โค้ดนี้จะทำสิ่งนี้ (...) และอันนั้น (...) -// ...แล้วก็ใครจะไปรู้ว่ามีอะไรอีก... +// โค้ดนี้จะทำสิ่งนี้ (...) และสิ่งนั้น (...) +// ...และใครจะรู้ว่ามันยังทำอะไรอีก... very; complex; code; ``` -แต่ในโค้ดที่ดี ปริมาณความคิดเห็น "อธิบาย" แบบนี้ควรน้อยที่สุด จริงๆ แล้ว โค้ดควรอ่านเข้าใจได้ง่ายโดยไม่ต้องมีมัน +แต่ในโค้ดที่ดี ปริมาณของคอมเมนต์ "อธิบาย" แบบนี้ควรมีให้น้อยที่สุด จริงๆ แล้ว โค้ดควรอ่านเข้าใจได้ง่ายโดยไม่ต้องพึ่งคอมเมนต์ -มีกฎเหล็กที่ยอดเยี่ยมเกี่ยวกับเรื่องนี้: "ถ้าโค้ดไม่ชัดเจนจนต้องใส่ความคิดเห็น เราอาจควรเขียนใหม่แทน" +มีกฎสำคัญเกี่ยวกับเรื่องนี้: "ถ้าโค้ดไม่ชัดเจนจนต้องใช้คอมเมนต์ บางทีอาจควรเขียนโค้ดใหม่แทน" -### เคล็ดลับ: แยกออกเป็นฟังก์ชัน +### เคล็ดลับ: แยกโค้ดออกมาเป็นฟังก์ชัน -บางครั้งการแทนที่โค้ดด้วยฟังก์ชันก็มีประโยชน์ เช่นในที่นี้: +บางครั้งการแทนที่ส่วนหนึ่งของโค้ดด้วยฟังก์ชันก็มีประโยชน์ เหมือนในตัวอย่างนี้: ```js function showPrimes(n) { nextPrime: for (let i = 2; i < n; i++) { - + *!* - // ตรวจว่า i เป็นจำนวนเฉพาะไหม + // ตรวจสอบว่า i เป็นจำนวนเฉพาะหรือไม่ for (let j = 2; j < i; j++) { if (i % j == 0) continue nextPrime; } @@ -43,8 +43,7 @@ function showPrimes(n) { } ``` -ตัวเลือกที่ดีกว่าคือแยกออกมาเป็นฟังก์ชัน `isPrime`: - +โค้ดที่ดีกว่า โดยการแยกเป็นฟังก์ชัน `isPrime` คือ: ```js function showPrimes(n) { @@ -52,7 +51,7 @@ function showPrimes(n) { for (let i = 2; i < n; i++) { *!*if (!isPrime(i)) continue;*/!* - alert(i); + alert(i); } } @@ -65,21 +64,21 @@ function isPrime(n) { } ``` -ตอนนี้เราเข้าใจโค้ดได้ง่ายแล้ว ตัวฟังก์ชันเองกลายเป็นความคิดเห็น โค้ดแบบนี้เรียกว่า *self-descriptive* +ตอนนี้เราสามารถเข้าใจโค้ดได้ง่ายขึ้น ฟังก์ชันเองก็กลายเป็นคอมเมนต์ โค้ดแบบนี้เรียกว่า *อธิบายตัวเอง (self-descriptive)* ### เคล็ดลับ: สร้างฟังก์ชัน -และถ้าเรามี "แผ่นโค้ด" ยาวๆ แบบนี้: +หากเรามี "แผ่นโค้ด" ยาวๆ แบบนี้: ```js -// เพิ่มวิสกี้ตรงนี้ +// ตรงนี้เติมวิสกี้ for(let i = 0; i < 10; i++) { let drop = getWhiskey(); smell(drop); add(drop, glass); } -// เพิ่มน้ำผลไม้ตรงนี้ +// ตรงนี้เติมน้ำผลไม้ for(let t = 0; t < 3; t++) { let tomato = getTomato(); examine(tomato); @@ -87,10 +86,10 @@ for(let t = 0; t < 3; t++) { add(juice, glass); } -// ... +// ... ``` -ลองรีแฟกเตอร์ให้เป็นฟังก์ชันอาจจะดีกว่า แบบนี้: +การ refactor ให้เป็นฟังก์ชันแบบนี้อาจดีกว่า: ```js addWhiskey(glass); @@ -108,30 +107,30 @@ function addJuice(container) { let tomato = getTomato(); //... } -} +} ``` -อีกครั้ง ฟังก์ชันเองก็บอกได้ว่ากำลังเกิดอะไรขึ้น ไม่ต้องใส่ความคิดเห็นอะไร และโครงสร้างโค้ดก็ดีขึ้นเมื่อแยกมัน มันชัดเจนว่าแต่ละฟังก์ชันทำอะไร รับอะไรเข้ามา และส่งอะไรกลับ +อีกครั้ง ตัวฟังก์ชันเองบอกเลยว่ากำลังเกิดอะไรขึ้น ไม่ต้องใช้คอมเมนต์อธิบาย และโครงสร้างโค้ดก็ดีขึ้นเมื่อแยกส่วนออกมา มองชัดเจนว่าแต่ละฟังก์ชันทำอะไร รับอะไรเข้ามา และส่งอะไรออกไป -ในความเป็นจริง เราไม่สามารถหลีกเลี่ยงความคิดเห็นแบบ "อธิบาย" ได้ทั้งหมด มีอัลกอริทึมที่ซับซ้อน และมี "กลเม็ด" ที่ฉลาดเพื่อปรับให้เหมาะสม แต่โดยทั่วไปแล้ว เราควรพยายามรักษาให้โค้ดเรียบง่ายและอธิบายตัวเอง +ในความเป็นจริง เราไม่สามารถหลีกเลี่ยงคอมเมนต์ "อธิบาย" ได้ทั้งหมด มีอัลกอริธึมที่ซับซ้อน และมี "กลเม็ด" ที่ชาญฉลาดที่ใช้เพื่อปรับปรุงประสิทธิภาพโค้ด แต่โดยทั่วไปแล้ว เราควรพยายามรักษาให้โค้ดเรียบง่ายและอธิบายตัวเองได้มากที่สุด -## ความคิดเห็นที่ดี +## คอมเมนต์ที่ดี -งั้นความคิดเห็นแบบอธิบายมักจะแย่สินะ แล้วความคิดเห็นแบบไหนดีล่ะ? +ดังนั้น คอมเมนต์ที่เป็นคำอธิบายมักจะไม่ดี แล้วคอมเมนต์แบบไหนถึงจะดีล่ะ? อธิบายสถาปัตยกรรม -: ให้ภาพรวมระดับสูงของคอมโพเนนต์ ว่ามันโต้ตอบกันอย่างไร อะไรคือลำดับการควบคุมในสถานการณ์ต่างๆ สรุปคือมุมมองแบบ bird's eye ของโค้ด มีภาษาพิเศษ [UML](http://wikipedia.org/wiki/Unified_Modeling_Language) เพื่อสร้างแผนภาพสถาปัตยกรรมระดับสูงที่อธิบายโค้ด ควรศึกษาอย่างยิ่ง +: ให้ภาพรวมในระดับสูงของส่วนประกอบต่างๆ ว่ามีปฏิสัมพันธ์กันอย่างไร อะไรคือลำดับการควบคุมในสถานการณ์ต่างๆ สั้นๆ ก็คือมุมสูงของโค้ด มีภาษาพิเศษอย่าง [UML](http://wikipedia.org/wiki/Unified_Modeling_Language) ที่ใช้สร้างแผนภาพสถาปัตยกรรมในระดับสูงเพื่ออธิบายโค้ด ซึ่งแน่นอนว่าคุ้มค่าแก่การศึกษา -เอกสารพารามิเตอร์ฟังก์ชันและการใช้งาน -: มี syntax พิเศษ [JSDoc](http://en.wikipedia.org/wiki/JSDoc) เพื่อเขียนเอกสารประกอบฟังก์ชัน: การใช้งาน พารามิเตอร์ ค่าที่ส่งกลับ +บันทึกพารามิเตอร์และการใช้งานฟังก์ชัน +: มีไวยากรณ์พิเศษอย่าง [JSDoc](http://en.wikipedia.org/wiki/JSDoc) สำหรับบันทึกข้อมูลฟังก์ชัน: วิธีใช้งาน พารามิเตอร์ ค่าที่ส่งคืน ตัวอย่างเช่น: ```js /** - * ส่งค่า x ยกกำลัง n กลับ + * ส่งคืน x ยกกำลัง n * - * @param {number} x ตัวเลขที่จะยกกำลัง - * @param {number} n เลขกำลัง ต้องเป็นจำนวนเต็มบวก + * @param {number} x เลขที่ต้องการยกกำลัง + * @param {number} n เลขชี้กำลัง ต้องเป็นจำนวนนับ * @return {number} x ยกกำลัง n */ function pow(x, n) { @@ -139,42 +138,42 @@ function pow(x, n) { } ``` -ความคิดเห็นแบบนี้ทำให้เราเข้าใจจุดประสงค์ของฟังก์ชัน และใช้มันได้ถูกต้องโดยไม่ต้องดูในโค้ด +คอมเมนต์แบบนี้ช่วยให้เราเข้าใจวัตถุประสงค์ของฟังก์ชันและใช้งานอย่างถูกต้องโดยไม่ต้องดูที่โค้ด -อีกอย่าง เอดิเตอร์หลายตัวเช่น [WebStorm](https://www.jetbrains.com/webstorm/) สามารถเข้าใจความคิดเห็นแบบนี้ได้ และใช้เพื่อทำออโต้คอมพลีตและตรวจสอบโค้ดบางส่วนโดยอัตโนมัติ +ในทางกลับกัน เครื่องมือแก้ไขโค้ดหลายตัวเช่น [WebStorm](https://www.jetbrains.com/webstorm/) ก็สามารถอ่านคอมเมนต์เหล่านี้และใช้เพื่อช่วยเติมโค้ดอัตโนมัติและตรวจสอบโค้ดบางอย่างโดยอัตโนมัติได้ -นอกจากนี้ยังมีเครื่องมือเช่น [JSDoc 3](https://github.com/jsdoc/jsdoc) ที่สามารถสร้างเอกสาร HTML จากความคิดเห็นได้ อ่านข้อมูลเพิ่มเติมเกี่ยวกับ JSDoc ได้ที่ +และยังมีเครื่องมืออย่าง [JSDoc 3](https://github.com/jsdoc/jsdoc) ที่สามารถสร้างเอกสาร HTML จากคอมเมนต์ คุณสามารถอ่านข้อมูลเพิ่มเติมเกี่ยวกับ JSDoc ได้ที่ -ทำไมงานถึงแก้ปัญหาแบบนี้? -: สิ่งที่เขียนลงไปนั้นสำคัญ แต่สิ่งที่*ไม่ได้*เขียนอาจสำคัญยิ่งกว่าในการทำความเข้าใจว่ากำลังเกิดอะไรขึ้น ทำไมงานถึงแก้ปัญหาแบบนี้อย่างเจาะจง? โค้ดไม่ได้ให้คำตอบ +ทำไมปัญหาถึงได้รับการแก้ไขด้วยวิธีนี้? +: สิ่งที่เขียนไว้นั้นสำคัญ แต่สิ่งที่ *ไม่ได้* เขียนอาจจะสำคัญยิ่งกว่าในการทำความเข้าใจว่ากำลังเกิดอะไรขึ้น ทำไมปัญหาถึงถูกแก้ไขด้วยวิธีนี้พอดี? โค้ดไม่ได้ให้คำตอบ - ถ้ามีหลายวิธีในการแก้ปัญหา ทำไมถึงใช้วิธีนี้? โดยเฉพาะอย่างยิ่งเมื่อมันไม่ใช่วิธีที่ชัดเจนที่สุด + ถ้ามีหลายวิธีในการแก้ปัญหา ทำไมถึงเลือกวิธีนี้? โดยเฉพาะอย่างยิ่งเมื่อมันไม่ใช่ทางเลือกที่ชัดเจนที่สุด - หากไม่มีความคิดเห็นแบบนี้ สถานการณ์ต่อไปนี้อาจเกิดขึ้นได้: - 1. คุณ (หรือเพื่อนร่วมงานของคุณ) เปิดโค้ดที่เขียนไว้นานแล้ว และเห็นว่ามัน "ไม่เหมาะสม" - 2. คุณคิด: "ตอนนั้นฉันโง่จัง แต่ตอนนี้ฉันฉลาดขึ้นมากแล้ว" แล้วเขียนใหม่โดยใช้ตัวเลือกที่ "ชัดเจนและถูกต้องกว่า" - 3. ...ความต้องการเขียนใหม่เป็นเรื่องดี แต่ในกระบวนการนั้น คุณพบว่าวิธีที่ "ชัดเจนกว่า" จริงๆ แล้วขาดอะไรบางอย่าง คุณยังจำได้เลือนรางว่าทำไม เพราะคุณเคยลองทำมานานแล้ว คุณย้อนกลับไปใช้ตัวเลือกที่ถูกต้อง แต่เสียเวลาไปแล้ว + หากไม่มีคอมเมนต์ดังกล่าว สถานการณ์ต่อไปนี้อาจเกิดขึ้นได้: + 1. คุณ (หรือเพื่อนร่วมงาน) เปิดโค้ดที่เขียนไว้เมื่อสักพักก่อน แล้วเห็นว่ามัน "ไม่เหมาะสมที่สุด" + 2. คุณคิดว่า "ตอนนั้นโง่จัง ส่วนตอนนี้ฉันฉลาดขึ้นมากแล้ว" และเขียนใหม่ด้วยทางเลือกที่ "ตรงไปตรงมาและถูกต้องกว่า" + 3. ...แรงผลักดันที่จะเขียนใหม่เป็นสิ่งที่ดี แต่ระหว่างนั้นคุณเห็นว่าวิธีที่ "ตรงไปตรงมา" นั้นจริงๆ แล้วไม่ครบถ้วน คุณพอจำได้เลือนราง ว่าทำไมถึงเป็นแบบนั้น เพราะเคยลองทำไปแล้วเมื่อนานมาแล้ว คุณเปลี่ยนกลับมาใช้วิธีที่ถูกต้อง แต่ก็เสียเวลาไปแล้ว - ความคิดเห็นที่อธิบายวิธีแก้ปัญหานั้นสำคัญมาก มันช่วยให้การพัฒนาดำเนินไปในทิศทางที่ถูกต้อง + คอมเมนต์ที่อธิบายวิธีแก้ปัญหานั้นสำคัญมาก ช่วยให้พัฒนาต่อไปในทิศทางที่ถูกต้อง -โค้ดมีรายละเอียดอะไรที่ซับซ้อนไหม? มันถูกใช้ที่ไหน? -: ถ้าโค้ดมีอะไรที่ซับซ้อนและขัดแย้งกับสามัญสำนึก มันควรค่าแก่การใส่ความคิดเห็นอย่างยิ่ง +โค้ดมีจุดอ่อนหรือเทคนิคพิเศษซ่อนอยู่ไหม? ใช้แบบนี้ที่ไหนบ้าง? +: ถ้าโค้ดมีอะไรที่ละเอียดอ่อนและขัดกับสัญชาตญาณ ก็ควรคอมเมนต์ไว้อย่างยิ่ง ## สรุป -สัญญาณสำคัญของนักพัฒนาที่ดีคือความคิดเห็น: ทั้งการมีอยู่และการไม่มีอยู่ของมัน +สัญญาณสำคัญของนักพัฒนาที่ดีคือคอมเมนต์: ทั้งการมีและการไม่มีของมัน -ความคิดเห็นที่ดีช่วยให้เราดูแลรักษาโค้ดได้ดี กลับมาดูมันหลังจากพักไปและใช้มันได้อย่างมีประสิทธิภาพมากขึ้น +คอมเมนต์ที่ดีช่วยให้เรารักษาโค้ดไว้ได้ดี กลับมาดูอีกครั้งหลังจากผ่านไประยะหนึ่ง และใช้งานได้อย่างมีประสิทธิภาพยิ่งขึ้น -**ใส่ความคิดเห็นเรื่องนี้:** +**ควรเขียนคอมเมนต์เรื่อง:** -- สถาปัตยกรรมโดยรวม ภาพรวมระดับสูง -- การใช้ฟังก์ชัน -- วิธีการแก้ปัญหาที่สำคัญ โดยเฉพาะอย่างยิ่งเมื่อมันไม่ชัดเจนในทันที +- สถาปัตยกรรมโดยรวม, มุมมองภาพกว้าง +- วิธีใช้ฟังก์ชัน +- วิธีแก้ปัญหาที่สำคัญ โดยเฉพาะเมื่อไม่เห็นได้ชัดในทันที -**หลีกเลี่ยงความคิดเห็น:** +**หลีกเลี่ยงคอมเมนต์ที่:** -- ที่บอกว่า "โค้ดทำงานอย่างไร" และ "มันทำอะไร" -- ใส่มันก็ต่อเมื่อเป็นไปไม่ได้ที่จะทำให้โค้ดเรียบง่ายและอธิบายตัวเองจนไม่ต้องใช้ความคิดเห็น +- บอก "โค้ดทำงานอย่างไร" และ "ทำอะไร" +- ใส่คอมเมนต์เฉพาะเมื่อทำให้โค้ดเรียบง่ายและอธิบายตัวเองจนไม่จำเป็นต้องใช้คอมเมนต์แล้วไม่ได้ -ความคิดเห็นยังใช้สำหรับเครื่องมือสร้างเอกสารอัตโนมัติเช่น JSDoc3: พวกมันจะอ่านความคิดเห็นและสร้างเอกสาร HTML (หรือเอกสารในรูปแบบอื่น) +คอมเมนต์ยังถูกใช้โดยเครื่องมือสร้างเอกสารอัตโนมัติอย่าง JSDoc3: อ่านคอมเมนต์และสร้างเอกสาร HTML (หรือเอกสารในรูปแบบอื่น) จากมัน \ No newline at end of file