นักพัฒนาจำนวนมากมักเลื่อนการเขียน documentation ไปจนถึงท้ายกระบวนการพัฒนา หลังจากเขียนโค้ดและทำ unit testing เสร็จแล้ว นี่เป็นวิธีที่แน่นอนที่สุดวิธีหนึ่งที่จะทำให้ได้ documentation คุณภาพต่ำ เวลาที่ดีที่สุดในการเขียนคอมเมนต์คือตอน เริ่มต้น ของกระบวนการ ขณะที่คุณกำลังเขียนโค้ด การเขียนคอมเมนต์ก่อนทำให้ documentation กลายเป็นส่วนหนึ่งของกระบวนการออกแบบ วิธีนี้ไม่เพียงแต่ให้ documentation ที่ดีขึ้น แต่ยังช่วยให้การออกแบบดีขึ้น และทำให้กระบวนการเขียน documentation สนุกยิ่งขึ้นอีกด้วย
15.1 การเลื่อนเขียนคอมเมนต์ทำให้คอมเมนต์แย่
นักพัฒนาเกือบทุกคนที่ผมเคยเจอชอบเลื่อนการเขียนคอมเมนต์ เมื่อถามว่าทำไมไม่เขียน documentation ตั้งแต่แรก พวกเขาบอกว่าโค้ดยังมีการเปลี่ยนแปลงอยู่ ถ้าเขียน documentation เร็วเกินไป พวกเขาบอกว่าจะต้องมาเขียนใหม่เมื่อโค้ดเปลี่ยน ดังนั้นรอให้โค้ดคงที่ก่อนดีกว่า แต่ผมเดาว่ายังมีเหตุผลอีกข้อหนึ่ง นั่นคือพวกเขามอง documentation เป็นงานน่าเบื่อ ดังนั้นจึงเลื่อนออกไปนานเท่าที่จะทำได้
น่าเสียดายที่วิธีนี้มีผลเสียหลายประการ อย่างแรก การเลื่อน documentation มักหมายความว่ามันจะไม่มีวันถูกเขียนเลย เมื่อคุณเริ่มเลื่อน มันง่ายที่จะเลื่อนออกไปอีกเล็กน้อย เพราะยังไงโค้ดก็จะคงที่มากขึ้นอีกในอีกไม่กี่สัปดาห์ พอถึงเวลาที่โค้ดคงที่อย่างไม่ต้องสงสัย ก็มีโค้ดจำนวนมากแล้ว ซึ่งหมายความว่างานเขียน documentation กลายเป็นเรื่องใหญ่โตและน่าสนใจน้อยลงไปอีก ไม่เคยมีช่วงเวลาที่สะดวกที่จะหยุดสักสองสามวันเพื่อเติมคอมเมนต์ที่ขาดหายไป และมันง่ายที่จะหาเหตุผลเข้าข้างตัวเองว่าสิ่งที่ดีที่สุดสำหรับโปรเจกต์คือการเดินหน้าต่อไป แก้บั๊ก หรือเขียนฟีเจอร์ใหม่ถัดไป ซึ่งจะสร้างโค้ดที่ไม่มี documentation เพิ่มขึ้นไปอีก
ถึงแม้ว่าคุณจะมีวินัยพอที่จะกลับมาเขียนคอมเมนต์ (และอย่าหลอกตัวเองนะว่าคุณมี ส่วนใหญ่คุณคงไม่มี) คอมเมนต์เหล่านั้นก็จะไม่ค่อยดีนัก เมื่อถึงจุดนี้ในกระบวนการ คุณก็ถอดใจไปแล้ว ในความคิดของคุณ โค้ดส่วนนี้เสร็จแล้ว และคุณอยากจะขยับไปทำโปรเจกต์ต่อไป คุณรู้ว่าการเขียนคอมเมนต์เป็นสิ่งที่ถูกต้อง แต่มันไม่สนุก คุณแค่อยากทำให้เสร็จเร็วที่สุด ดังนั้นคุณก็กวาดสายตาผ่านโค้ดอย่างรวดเร็ว เพิ่มคอมเมนต์พอให้ดูดี ถึงตอนนี้ก็ผ่านมานานแล้วตั้งแต่คุณออกแบบโค้ด ความทรงจำเกี่ยวกับกระบวนการออกแบบเริ่มเลือนราง คุณมองที่โค้ดขณะเขียนคอมเมนต์ ดังนั้นคอมเมนต์ก็แค่พูดซ้ำสิ่งที่โค้ดบอก แม้คุณจะพยายามสร้างแนวคิดการออกแบบที่ไม่ได้ชัดเจนจากโค้ดขึ้นมาใหม่ ก็จะมีสิ่งที่คุณจำไม่ได้ ดังนั้นคอมเมนต์จึงขาดสิ่งที่สำคัญที่สุดบางอย่างที่มันควรจะอธิบาย
15.2 เขียนคอมเมนต์ก่อน
ผมใช้วิธีที่แตกต่างในการเขียนคอมเมนต์ โดยผมจะเขียนคอมเมนต์ตั้งแต่เริ่มต้นเลย:
- สำหรับคลาสใหม่ ผมเริ่มต้นด้วยการเขียน class interface comment
- ถัดมา ผมเขียน interface comments และ signatures สำหรับ public methods ที่สำคัญที่สุด แต่ปล่อยให้ method bodies ว่างไว้
- ผมปรับแต่งคอมเมนต์เหล่านี้สักเล็กน้อยจนกว่าโครงสร้างพื้นฐานจะดูเหมาะสม
- ถึงจุดนี้ ผมเขียน declarations และ comments สำหรับ class instance variables ที่สำคัญที่สุดในคลาส
- สุดท้าย ผมเติม method bodies พร้อมเพิ่ม implementation comments ตามที่จำเป็น
- ขณะเขียน method bodies ผมมักจะค้นพบว่าต้องการ methods และ instance variables เพิ่มเติม สำหรับแต่ละ method ใหม่ ผมจะเขียน interface comment ก่อน method body ส่วน instance variables ผมจะเติม comment ไปพร้อมกับการเขียน variable declaration
เมื่อโค้ดเสร็จ คอมเมนต์ก็เสร็จด้วย ไม่มี backlog ของคอมเมนต์ที่ยังไม่ได้เขียนอีกต่อไป
แนวทางการเขียนคอมเมนต์ก่อนมีประโยชน์สามประการ อย่างแรก มันให้คอมเมนต์ที่ดีขึ้น ถ้าคุณเขียนคอมเมนต์ขณะที่คุณกำลังออกแบบคลาส ประเด็นการออกแบบที่สำคัญจะยังสดใหม่ในความทรงจำ ทำให้ง่ายต่อการบันทึกไว้ การเขียน interface comment สำหรับแต่ละ method ก่อน method body จะดีกว่า เพราะคุณจะได้โฟกัสที่ abstraction และ interface ของ method โดยไม่ถูกรบกวนด้วย implementation ของมัน ในระหว่างกระบวนการเขียนโค้ดและทดสอบ คุณจะสังเกตเห็นและแก้ไขปัญหาของคอมเมนต์ ผลลัพธ์คือคอมเมนต์จะดีขึ้นเรื่อยๆ ตลอดช่วงของการพัฒนา
15.3 คอมเมนต์คือเครื่องมือออกแบบ
ประโยชน์ประการที่สอง และสำคัญที่สุด ของการเขียนคอมเมนต์ตั้งแต่เริ่มต้นคือมันช่วยปรับปรุงการออกแบบระบบ คอมเมนต์เป็นวิธีเดียวที่จะ capture abstractions ได้อย่างสมบูรณ์ และ abstractions ที่ดีนั้นเป็นพื้นฐานของ system design ที่ดี ถ้าคุณเขียนคอมเมนต์ที่อธิบาย abstractions ตั้งแต่เริ่มต้น คุณสามารถทบทวนและปรับแต่งมันก่อนที่จะเขียน implementation code ในการเขียนคอมเมนต์ที่ดี คุณต้องระบุ essence ของตัวแปรหรือชิ้นส่วนของโค้ดให้ได้: อะไรคือสิ่งที่สำคัญที่สุดของสิ่งนี้? การทำสิ่งนี้ตั้งแต่ช่วงต้นของกระบวนการออกแบบเป็นสิ่งสำคัญ ไม่เช่นนั้นคุณก็แค่เขียนโค้ดแบบสุ่มๆ
คอมเมนต์ทำหน้าที่เสมือนนกคานารีในเหมืองถ่านหินของความซับซ้อน ถ้า method หรือตัวแปรต้องการคอมเมนต์ที่ยาว มันคือ red flag ที่บอกว่าคุณไม่มี abstraction ที่ดี จำได้ไหมจาก Chapter 4 ว่าคลาสควรจะลึก (deep): คลาสที่ดีที่สุดมี interfaces ที่เรียบง่ายมากแต่ implement ฟังก์ชันที่มีพลัง วิธีที่ดีที่สุดในการตัดสินความซับซ้อนของ interface คือดูจากคอมเมนต์ที่อธิบายมัน ถ้า interface comment ของ method ให้ข้อมูลทั้งหมดที่จำเป็นในการใช้งาน method และยังสั้นและเรียบง่าย นั่นบ่งชี้ว่า method มี interface ที่เรียบง่าย ในทางกลับกัน ถ้าไม่มีวิธีที่จะอธิบาย method ได้อย่างสมบูรณ์โดยไม่ต้องใช้คอมเมนต์ที่ยาวและซับซ้อน แสดงว่า method มี interface ที่ซับซ้อน คุณสามารถเปรียบเทียบ interface comment ของ method กับ implementation เพื่อวัดว่า method นั้นลึกแค่ไหน: ถ้า interface comment ต้องอธิบายคุณสมบัติหลักทั้งหมดของ implementation แสดงว่า method นั้นตื้น (shallow) แนวคิดเดียวกันนี้ใช้กับตัวแปร: ถ้าต้องใช้คอมเมนต์ยาวเพื่ออธิบายตัวแปรอย่างสมบูรณ์ นั่นคือ red flag ที่บ่งชี้ว่าคุณอาจเลือก decomposition ของตัวแปรไม่ถูกต้อง โดยรวมแล้ว การเขียนคอมเมนต์ช่วยให้คุณประเมินการตัดสินใจในการออกแบบได้ตั้งแต่เนิ่นๆ คุณจึงสามารถค้นพบและแก้ไขปัญหาได้
Red Flag: Hard to Describe (ธงแดง: อธิบายได้ยาก)
คอมเมนต์ที่อธิบาย method หรือตัวแปรควรเรียบง่ายแต่สมบูรณ์ ถ้าคุณพบว่าการเขียนคอมเมนต์แบบนั้นเป็นเรื่องยาก นั่นเป็นตัวบ่งชี้ว่าอาจมีปัญหากับการออกแบบของสิ่งที่คุณกำลังอธิบายอยู่
แน่นอนว่าคอมเมนต์จะเป็นตัวบ่งชี้ความซับซ้อนที่ดีก็ต่อเมื่อมันสมบูรณ์และชัดเจน ถ้าคุณเขียน method interface comment ที่ไม่ได้ให้ข้อมูลทั้งหมดที่จำเป็นในการเรียกใช้ method หรือเขียนแบบ cryptic จนเข้าใจยาก คอมเมนต์นั้นก็ไม่ใช่วัดความลึก (depth) ของ method ที่ดี
15.4 คอมเมนต์ที่เขียนตั้งแต่เนิ่นๆ คือคอมเมนต์ที่สนุก
ประโยชน์ประการที่สามและประการสุดท้ายของการเขียนคอมเมนต์ตั้งแต่เนิ่นๆ คือมันทำให้การเขียนคอมเมนต์สนุกขึ้น สำหรับผมแล้ว ส่วนที่สนุกที่สุดอย่างหนึ่งของการเขียนโปรแกรมคือช่วงต้นของการออกแบบคลาสใหม่ ซึ่งผมกำลังขัดเกลา abstractions และโครงสร้างของคลาส คอมเมนต์ส่วนใหญ่ของผมถูกเขียนในช่วงนี้ และคอมเมนต์คือวิธีที่ผมบันทึกและทดสอบคุณภาพของการตัดสินใจในการออกแบบของผม ผมมองหาการออกแบบที่สามารถแสดงออกได้อย่างสมบูรณ์และชัดเจนด้วยคำพูดที่น้อยที่สุด ยิ่งคอมเมนต์เรียบง่ายเท่าไหร่ ผมก็ยิ่งรู้สึกดีกับการออกแบบของผมมากขึ้นเท่านั้น ดังนั้นการหาคอมเมนต์ที่เรียบง่ายจึงเป็นเรื่องน่าภูมิใจ ถ้าคุณเขียนโปรแกรมอย่างมีกลยุทธ์ (strategic programming) โดยที่เป้าหมายหลักคือการออกแบบที่ยอดเยี่ยม ไม่ใช่แค่เขียนโค้ดที่ทำงานได้ การเขียนคอมเมนต์ควรจะเป็นเรื่องสนุก เพราะนั่นคือวิธีที่คุณระบุการออกแบบที่ดีที่สุด
15.5 การเขียนคอมเมนต์ตั้งแต่เนิ่นๆ มีต้นทุนแพงไหม?
ทีนี้ลองกลับมาดูข้อโต้แย้งที่สนับสนุนการเลื่อนเขียนคอมเมนต์ นั่นคือการหลีกเลี่ยงต้นทุนในการแก้ไขคอมเมนต์เมื่อโค้ดเปลี่ยนไป การคำนวณแบบคร่าวๆ จะแสดงให้เห็นว่าวิธีนี้ไม่ได้ช่วยประหยัดอะไรมากนัก อย่างแรก ลองประมาณสัดส่วนของเวลาในการพัฒนาทั้งหมดที่คุณใช้พิมพ์โค้ดและคอมเมนต์ รวมถึงเวลาในการแก้ไขโค้ดและคอมเมนต์ มันไม่น่าจะเกิน 10% ของเวลาพัฒนาทั้งหมด ถึงแม้ว่าครึ่งหนึ่งของบรรทัดโค้ดทั้งหมดของคุณจะเป็นคอมเมนต์ การเขียนคอมเมนต์ก็คงไม่เกิน 5% ของเวลาพัฒนาทั้งหมด การเลื่อนเขียนคอมเมนต์ไปจนจบจะช่วยประหยัดได้เพียงเศษเสี้ยวของส่วนนี้ ซึ่งไม่มากเลย
การเขียนคอมเมนต์ก่อนจะทำให้ abstractions มีความเสถียรมากขึ้นก่อนที่คุณจะเริ่มเขียนโค้ด ซึ่งน่าจะช่วยประหยัดเวลาในการเขียนโค้ด ในทางตรงกันข้าม ถ้าคุณเขียนโค้ดก่อน abstractions มักจะเปลี่ยนแปลงไปขณะที่คุณเขียนโค้ด ซึ่งจะต้องมีการแก้ไขโค้ดมากกว่าแนวทางการเขียนคอมเมนต์ก่อน เมื่อคุณพิจารณาปัจจัยทั้งหมดเหล่านี้แล้ว เป็นไปได้ว่าการเขียนคอมเมนต์ก่อนอาจจะเร็วกว่าโดยรวม
15.6 บทสรุป
ถ้าคุณไม่เคยลองเขียนคอมเมนต์ก่อน ลองดูสักครั้ง ลองทำไปนานพอที่จะชินกับมัน แล้วลองคิดดูว่ามันส่งผลต่อคุณภาพของคอมเมนต์ คุณภาพของการออกแบบ และความสุขโดยรวมในการพัฒนาซอฟต์แวร์ของคุณอย่างไร หลังจากที่คุณได้ลองสักพัก บอกผมหน่อยว่าประสบการณ์ของคุณตรงกับของผมหรือไม่ และเพราะอะไร