From 45f6a2c38e1e7a20b3ba8166905ddefddf88cb43 Mon Sep 17 00:00:00 2001 From: Prasit Tongpradit Date: Sun, 7 Apr 2024 18:56:34 +0700 Subject: [PATCH 1/2] =?UTF-8?q?=E0=B8=84=E0=B8=AD=E0=B8=A1=E0=B9=80?= =?UTF-8?q?=E0=B8=A1=E0=B8=99=E0=B8=95=E0=B9=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 1-js/03-code-quality/03-comments/article.md | 115 +++++--------------- 1 file changed, 25 insertions(+), 90 deletions(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index 9aa51eb64..f131b2269 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,73 +107,9 @@ function addJuice(container) { let tomato = getTomato(); //... } -} -``` - -อีกครั้ง ฟังก์ชันเองก็บอกได้ว่ากำลังเกิดอะไรขึ้น ไม่ต้องใส่ความคิดเห็นอะไร และโครงสร้างโค้ดก็ดีขึ้นเมื่อแยกมัน มันชัดเจนว่าแต่ละฟังก์ชันทำอะไร รับอะไรเข้ามา และส่งอะไรกลับ - -ในความเป็นจริง เราไม่สามารถหลีกเลี่ยงความคิดเห็นแบบ "อธิบาย" ได้ทั้งหมด มีอัลกอริทึมที่ซับซ้อน และมี "กลเม็ด" ที่ฉลาดเพื่อปรับให้เหมาะสม แต่โดยทั่วไปแล้ว เราควรพยายามรักษาให้โค้ดเรียบง่ายและอธิบายตัวเอง - -## ความคิดเห็นที่ดี - -งั้นความคิดเห็นแบบอธิบายมักจะแย่สินะ แล้วความคิดเห็นแบบไหนดีล่ะ? - -อธิบายสถาปัตยกรรม -: ให้ภาพรวมระดับสูงของคอมโพเนนต์ ว่ามันโต้ตอบกันอย่างไร อะไรคือลำดับการควบคุมในสถานการณ์ต่างๆ สรุปคือมุมมองแบบ bird's eye ของโค้ด มีภาษาพิเศษ [UML](http://wikipedia.org/wiki/Unified_Modeling_Language) เพื่อสร้างแผนภาพสถาปัตยกรรมระดับสูงที่อธิบายโค้ด ควรศึกษาอย่างยิ่ง - -เอกสารพารามิเตอร์ฟังก์ชันและการใช้งาน -: มี syntax พิเศษ [JSDoc](http://en.wikipedia.org/wiki/JSDoc) เพื่อเขียนเอกสารประกอบฟังก์ชัน: การใช้งาน พารามิเตอร์ ค่าที่ส่งกลับ - -ตัวอย่างเช่น: -```js -/** - * ส่งค่า x ยกกำลัง n กลับ - * - * @param {number} x ตัวเลขที่จะยกกำลัง - * @param {number} n เลขกำลัง ต้องเป็นจำนวนเต็มบวก - * @return {number} x ยกกำลัง n - */ -function pow(x, n) { - ... -} +} ``` -ความคิดเห็นแบบนี้ทำให้เราเข้าใจจุดประสงค์ของฟังก์ชัน และใช้มันได้ถูกต้องโดยไม่ต้องดูในโค้ด - -อีกอย่าง เอดิเตอร์หลายตัวเช่น [WebStorm](https://www.jetbrains.com/webstorm/) สามารถเข้าใจความคิดเห็นแบบนี้ได้ และใช้เพื่อทำออโต้คอมพลีตและตรวจสอบโค้ดบางส่วนโดยอัตโนมัติ - -นอกจากนี้ยังมีเครื่องมือเช่น [JSDoc 3](https://github.com/jsdoc/jsdoc) ที่สามารถสร้างเอกสาร HTML จากความคิดเห็นได้ อ่านข้อมูลเพิ่มเติมเกี่ยวกับ JSDoc ได้ที่ - -ทำไมงานถึงแก้ปัญหาแบบนี้? -: สิ่งที่เขียนลงไปนั้นสำคัญ แต่สิ่งที่*ไม่ได้*เขียนอาจสำคัญยิ่งกว่าในการทำความเข้าใจว่ากำลังเกิดอะไรขึ้น ทำไมงานถึงแก้ปัญหาแบบนี้อย่างเจาะจง? โค้ดไม่ได้ให้คำตอบ - - ถ้ามีหลายวิธีในการแก้ปัญหา ทำไมถึงใช้วิธีนี้? โดยเฉพาะอย่างยิ่งเมื่อมันไม่ใช่วิธีที่ชัดเจนที่สุด - - หากไม่มีความคิดเห็นแบบนี้ สถานการณ์ต่อไปนี้อาจเกิดขึ้นได้: - 1. คุณ (หรือเพื่อนร่วมงานของคุณ) เปิดโค้ดที่เขียนไว้นานแล้ว และเห็นว่ามัน "ไม่เหมาะสม" - 2. คุณคิด: "ตอนนั้นฉันโง่จัง แต่ตอนนี้ฉันฉลาดขึ้นมากแล้ว" แล้วเขียนใหม่โดยใช้ตัวเลือกที่ "ชัดเจนและถูกต้องกว่า" - 3. ...ความต้องการเขียนใหม่เป็นเรื่องดี แต่ในกระบวนการนั้น คุณพบว่าวิธีที่ "ชัดเจนกว่า" จริงๆ แล้วขาดอะไรบางอย่าง คุณยังจำได้เลือนรางว่าทำไม เพราะคุณเคยลองทำมานานแล้ว คุณย้อนกลับไปใช้ตัวเลือกที่ถูกต้อง แต่เสียเวลาไปแล้ว - - ความคิดเห็นที่อธิบายวิธีแก้ปัญหานั้นสำคัญมาก มันช่วยให้การพัฒนาดำเนินไปในทิศทางที่ถูกต้อง - -โค้ดมีรายละเอียดอะไรที่ซับซ้อนไหม? มันถูกใช้ที่ไหน? -: ถ้าโค้ดมีอะไรที่ซับซ้อนและขัดแย้งกับสามัญสำนึก มันควรค่าแก่การใส่ความคิดเห็นอย่างยิ่ง - -## สรุป - -สัญญาณสำคัญของนักพัฒนาที่ดีคือความคิดเห็น: ทั้งการมีอยู่และการไม่มีอยู่ของมัน - -ความคิดเห็นที่ดีช่วยให้เราดูแลรักษาโค้ดได้ดี กลับมาดูมันหลังจากพักไปและใช้มันได้อย่างมีประสิทธิภาพมากขึ้น - -**ใส่ความคิดเห็นเรื่องนี้:** - -- สถาปัตยกรรมโดยรวม ภาพรวมระดับสูง -- การใช้ฟังก์ชัน -- วิธีการแก้ปัญหาที่สำคัญ โดยเฉพาะอย่างยิ่งเมื่อมันไม่ชัดเจนในทันที - -**หลีกเลี่ยงความคิดเห็น:** - -- ที่บอกว่า "โค้ดทำงานอย่างไร" และ "มันทำอะไร" -- ใส่มันก็ต่อเมื่อเป็นไปไม่ได้ที่จะทำให้โค้ดเรียบง่ายและอธิบายตัวเองจนไม่ต้องใช้ความคิดเห็น +อีกครั้ง ตัวฟังก์ชันเองบอกเลยว่ากำลังเกิดอะไรขึ้น ไม่ต้องใช้คอมเมนต์อธิบาย และโครงสร้างโค้ดก็ดีขึ้นเมื่อแยกส่วนออกมา มองชัดเจนว่าแต่ละฟังก์ชันทำอะไร รับอะไรเข้ามา และส่งอะไรออกไป -ความคิดเห็นยังใช้สำหรับเครื่องมือสร้างเอกสารอัตโนมัติเช่น JSDoc3: พวกมันจะอ่านความคิดเห็นและสร้างเอกสาร HTML (หรือเอกสารในรูปแบบอื่น) +ในความเป็นจริง เราไม่สามารถหลีกเลี่ยงคอมเมนต์ "อธิบาย" ได้ทั้งหมด มีอัลกอริธึมที่ซับซ้อน และมี "กลเม็ด" ที่ชาญฉลาดที่ใช้เพื่อปรับปรุงประสิทธิภาพโค้ด แต่โดยทั่วไปแล้ว เราควรพยายามรักษาให้โค้ดเรียบง่ายและอธิบายตัวเองได้มากที่สุด \ No newline at end of file From 3cfd54eaa59a3f75af7d7dbe1e67225664ed04c1 Mon Sep 17 00:00:00 2001 From: Prasit Tongpradit Date: Sun, 7 Apr 2024 19:03:46 +0700 Subject: [PATCH 2/2] =?UTF-8?q?=E0=B8=84=E0=B8=AD=E0=B8=A1=E0=B9=80?= =?UTF-8?q?=E0=B8=A1=E0=B8=99=E0=B8=95=E0=B9=8C=E0=B8=97=E0=B8=B5=E0=B9=88?= =?UTF-8?q?=E0=B8=94=E0=B8=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 1-js/03-code-quality/03-comments/article.md | 66 ++++++++++++++++++++- 1 file changed, 65 insertions(+), 1 deletion(-) diff --git a/1-js/03-code-quality/03-comments/article.md b/1-js/03-code-quality/03-comments/article.md index f131b2269..0adb7e6bc 100644 --- a/1-js/03-code-quality/03-comments/article.md +++ b/1-js/03-code-quality/03-comments/article.md @@ -112,4 +112,68 @@ function addJuice(container) { อีกครั้ง ตัวฟังก์ชันเองบอกเลยว่ากำลังเกิดอะไรขึ้น ไม่ต้องใช้คอมเมนต์อธิบาย และโครงสร้างโค้ดก็ดีขึ้นเมื่อแยกส่วนออกมา มองชัดเจนว่าแต่ละฟังก์ชันทำอะไร รับอะไรเข้ามา และส่งอะไรออกไป -ในความเป็นจริง เราไม่สามารถหลีกเลี่ยงคอมเมนต์ "อธิบาย" ได้ทั้งหมด มีอัลกอริธึมที่ซับซ้อน และมี "กลเม็ด" ที่ชาญฉลาดที่ใช้เพื่อปรับปรุงประสิทธิภาพโค้ด แต่โดยทั่วไปแล้ว เราควรพยายามรักษาให้โค้ดเรียบง่ายและอธิบายตัวเองได้มากที่สุด \ No newline at end of file +ในความเป็นจริง เราไม่สามารถหลีกเลี่ยงคอมเมนต์ "อธิบาย" ได้ทั้งหมด มีอัลกอริธึมที่ซับซ้อน และมี "กลเม็ด" ที่ชาญฉลาดที่ใช้เพื่อปรับปรุงประสิทธิภาพโค้ด แต่โดยทั่วไปแล้ว เราควรพยายามรักษาให้โค้ดเรียบง่ายและอธิบายตัวเองได้มากที่สุด + +## คอมเมนต์ที่ดี + +ดังนั้น คอมเมนต์ที่เป็นคำอธิบายมักจะไม่ดี แล้วคอมเมนต์แบบไหนถึงจะดีล่ะ? + +อธิบายสถาปัตยกรรม +: ให้ภาพรวมในระดับสูงของส่วนประกอบต่างๆ ว่ามีปฏิสัมพันธ์กันอย่างไร อะไรคือลำดับการควบคุมในสถานการณ์ต่างๆ สั้นๆ ก็คือมุมสูงของโค้ด มีภาษาพิเศษอย่าง [UML](http://wikipedia.org/wiki/Unified_Modeling_Language) ที่ใช้สร้างแผนภาพสถาปัตยกรรมในระดับสูงเพื่ออธิบายโค้ด ซึ่งแน่นอนว่าคุ้มค่าแก่การศึกษา + +บันทึกพารามิเตอร์และการใช้งานฟังก์ชัน +: มีไวยากรณ์พิเศษอย่าง [JSDoc](http://en.wikipedia.org/wiki/JSDoc) สำหรับบันทึกข้อมูลฟังก์ชัน: วิธีใช้งาน พารามิเตอร์ ค่าที่ส่งคืน + +ตัวอย่างเช่น: +```js +/** + * ส่งคืน x ยกกำลัง n + * + * @param {number} x เลขที่ต้องการยกกำลัง + * @param {number} n เลขชี้กำลัง ต้องเป็นจำนวนนับ + * @return {number} x ยกกำลัง n + */ +function pow(x, n) { + ... +} +``` + +คอมเมนต์แบบนี้ช่วยให้เราเข้าใจวัตถุประสงค์ของฟังก์ชันและใช้งานอย่างถูกต้องโดยไม่ต้องดูที่โค้ด + +ในทางกลับกัน เครื่องมือแก้ไขโค้ดหลายตัวเช่น [WebStorm](https://www.jetbrains.com/webstorm/) ก็สามารถอ่านคอมเมนต์เหล่านี้และใช้เพื่อช่วยเติมโค้ดอัตโนมัติและตรวจสอบโค้ดบางอย่างโดยอัตโนมัติได้ + +และยังมีเครื่องมืออย่าง [JSDoc 3](https://github.com/jsdoc/jsdoc) ที่สามารถสร้างเอกสาร HTML จากคอมเมนต์ คุณสามารถอ่านข้อมูลเพิ่มเติมเกี่ยวกับ JSDoc ได้ที่ + +ทำไมปัญหาถึงได้รับการแก้ไขด้วยวิธีนี้? +: สิ่งที่เขียนไว้นั้นสำคัญ แต่สิ่งที่ *ไม่ได้* เขียนอาจจะสำคัญยิ่งกว่าในการทำความเข้าใจว่ากำลังเกิดอะไรขึ้น ทำไมปัญหาถึงถูกแก้ไขด้วยวิธีนี้พอดี? โค้ดไม่ได้ให้คำตอบ + + ถ้ามีหลายวิธีในการแก้ปัญหา ทำไมถึงเลือกวิธีนี้? โดยเฉพาะอย่างยิ่งเมื่อมันไม่ใช่ทางเลือกที่ชัดเจนที่สุด + + หากไม่มีคอมเมนต์ดังกล่าว สถานการณ์ต่อไปนี้อาจเกิดขึ้นได้: + 1. คุณ (หรือเพื่อนร่วมงาน) เปิดโค้ดที่เขียนไว้เมื่อสักพักก่อน แล้วเห็นว่ามัน "ไม่เหมาะสมที่สุด" + 2. คุณคิดว่า "ตอนนั้นโง่จัง ส่วนตอนนี้ฉันฉลาดขึ้นมากแล้ว" และเขียนใหม่ด้วยทางเลือกที่ "ตรงไปตรงมาและถูกต้องกว่า" + 3. ...แรงผลักดันที่จะเขียนใหม่เป็นสิ่งที่ดี แต่ระหว่างนั้นคุณเห็นว่าวิธีที่ "ตรงไปตรงมา" นั้นจริงๆ แล้วไม่ครบถ้วน คุณพอจำได้เลือนราง ว่าทำไมถึงเป็นแบบนั้น เพราะเคยลองทำไปแล้วเมื่อนานมาแล้ว คุณเปลี่ยนกลับมาใช้วิธีที่ถูกต้อง แต่ก็เสียเวลาไปแล้ว + + คอมเมนต์ที่อธิบายวิธีแก้ปัญหานั้นสำคัญมาก ช่วยให้พัฒนาต่อไปในทิศทางที่ถูกต้อง + +โค้ดมีจุดอ่อนหรือเทคนิคพิเศษซ่อนอยู่ไหม? ใช้แบบนี้ที่ไหนบ้าง? +: ถ้าโค้ดมีอะไรที่ละเอียดอ่อนและขัดกับสัญชาตญาณ ก็ควรคอมเมนต์ไว้อย่างยิ่ง + +## สรุป + +สัญญาณสำคัญของนักพัฒนาที่ดีคือคอมเมนต์: ทั้งการมีและการไม่มีของมัน + +คอมเมนต์ที่ดีช่วยให้เรารักษาโค้ดไว้ได้ดี กลับมาดูอีกครั้งหลังจากผ่านไประยะหนึ่ง และใช้งานได้อย่างมีประสิทธิภาพยิ่งขึ้น + +**ควรเขียนคอมเมนต์เรื่อง:** + +- สถาปัตยกรรมโดยรวม, มุมมองภาพกว้าง +- วิธีใช้ฟังก์ชัน +- วิธีแก้ปัญหาที่สำคัญ โดยเฉพาะเมื่อไม่เห็นได้ชัดในทันที + +**หลีกเลี่ยงคอมเมนต์ที่:** + +- บอก "โค้ดทำงานอย่างไร" และ "ทำอะไร" +- ใส่คอมเมนต์เฉพาะเมื่อทำให้โค้ดเรียบง่ายและอธิบายตัวเองจนไม่จำเป็นต้องใช้คอมเมนต์แล้วไม่ได้ + +คอมเมนต์ยังถูกใช้โดยเครื่องมือสร้างเอกสารอัตโนมัติอย่าง JSDoc3: อ่านคอมเมนต์และสร้างเอกสาร HTML (หรือเอกสารในรูปแบบอื่น) จากมัน \ No newline at end of file