(ใช้ Comment เป็นส่วนหนึ่งของขั้นตอนการออกแบบ)
นักพัฒนาจำนวนมากหลีกเลี่ยงการเขียน Documentation จนกว่าจะสิ้นสุดขั้นตอนการพัฒนา หลังจากเขียนโค้ดและทำการ Unit Testing เสร็จเรียบร้อย นี่เป็นวิธีที่มั่นใจได้สูงสุดในการสร้าง Documentation ที่มีคุณภาพต่ำ เวลาที่ดีที่สุดในการเขียน Comment คือ ตั้งแต่ต้นขั้นตอน ขณะที่คุณเขียนโค้ด การเขียน Comment ก่อนทำให้ Documentation เป็นส่วนหนึ่งของขั้นตอนการออกแบบ ไม่เพียงแต่ว่าวิธีนี้สร้าง Documentation ที่ดีกว่า แต่ยังช่วยสร้างการออกแบบที่ดีกว่า และทำให้ขั้นตอนการเขียน Documentation มีความสุขยิ่งขึ้น
15.1 Comment ที่ล่าช้าเป็น Comment ที่แย่
นักพัฒนาเกือบทุกคนที่เคยพบมา ต่างก็หลีกเลี่ยงการเขียน Comment เมื่อถูกถามว่าทำไมพวกเขาไม่เขียน Documentation ตั้งแต่เร็วๆ พวกเขากล่าวว่าโค้ดยังอยู่ในระหว่างการเปลี่ยนแปลง ถ้าพวกเขาเขียน Documentation ตั้งแต่เร็ว พวกเขากล่าวว่า พวกเขาจะต้องเขียนใหม่เมื่อโค้ดเปลี่ยนแปลง ดีกว่ารอจนกว่าโค้ดจะเสถียร อย่างไรก็ตาม ผมสงสัยว่ามีเหตุผลอื่น ซึ่งก็คือ พวกเขามองว่า Documentation เป็นงานหนักที่น่าเบื่อ ดังนั้นพวกเขาจึงหลีกเลี่ยงมันให้นานที่สุดเท่าที่จะเป็นไปได้
น่าเสียดายที่แนวทางนี้มีผลเสียหลายประการ อย่างแรก การล่าช้าในการเขียน Documentation มักจะหมายความว่า มันไม่เคยถูกเขียนเลย เมื่อคุณเริ่มล่าช้า การล่าช้าเพิ่มเติมนั้นเป็นเรื่องง่าย ท้ายที่สุดแล้ว โค้ดจะมีความเสถียรมากขึ้นในอีกไม่กี่สัปดาห์ที่จะมาถึง เมื่อโค้ดมีความเสถียรอย่างไม่ต้องสงสัย มีจำนวนมาก ซึ่งหมายความว่างาน Document ได้กลายเป็นเรื่องใหญ่ โตขึ้น และน่าน่าเบื่อมากยิ่งขึ้น ไม่มีเวลาที่สะดวกในการหยุดชั่วคราวเพื่อเติม Comment ที่ขาดหายไปทั้งหมด และเป็นเรื่องง่ายในการหาเหตุผลว่า สิ่งที่ดีที่สุดสำหรับโครงการคือการดำเนินต่อและแก้ไข Bug หรือเขียน Feature ใหม่ สิ่งนี้จะสร้างโค้ดที่ไม่มี Document เพิ่มเติม
แม้ว่าคุณจะมีวินัยในการกลับไปและเขียน Comment (และอย่าหลอกตัวเอง: คุณอาจจะไม่ทำ) Comment จะไม่ดีมาก ในเวลานี้ของขั้นตอนนี้ คุณได้ตัดสินใจจิตใจแล้ว ในความคิด piece of code นี้เสร็จแล้ว คุณตั้งหน้าตั้งตาไปสู่โครงการถัดไป คุณรู้ว่าการเขียน Comment คือสิ่งที่ควรทำ แต่มันไม่เป็นเรื่องสนุก คุณแค่อยากผ่านมันไปอย่างรวดเร็ว ดังนั้น คุณทำการผ่านโค้ดอย่างรวดเร็ว เพิ่มเติม Comment เพียงพอให้ดูเหมาะสม ในเวลานี้ ผ่านไปหลายช่วงเวลาแล้วตั้งแต่คุณออกแบบโค้ด ดังนั้น ความทรงจำของคุณเกี่ยวกับขั้นตอนการออกแบบกำลังจางหายไป คุณดูโค้ดขณะที่คุณเขียน Comment ดังนั้น Comment จึงซ้ำกับโค้ด แม้ว่าคุณพยายามสร้างความคิด Design ใหม่ที่ไม่เห็นได้ชัดเจนจากโค้ด ก็ยังมีสิ่งที่คุณไม่จำได้ ดังนั้น Comment จึงขาดสิ่งที่สำคัญที่สุดที่ควรอธิบาย
15.2 เขียน Comment ก่อน
ผมใช้วิธีที่แตกต่างไปในการเขียน Comment ซึ่งผมเขียน Comment ตั้งแต่เริ่มต้นอย่างแท้จริง:
- สำหรับ Class ใหม่ ผมเริ่มต้นด้วยการเขียน Comment Interface ของ Class
- ต่อไป ผมเขียน Comment Interface และ Signature สำหรับ Public Method ที่สำคัญที่สุด แต่ผมปล่อยให้ Method Body ว่าง
- ผมทำซ้ำสักเล็กน้อยใน Comment เหล่านี้จนกว่า Structure พื้นฐานจะรู้สึกเหมาะสม
- ณ จุดนี้ ผมเขียน Declaration และ Comment สำหรับ Instance Variable ที่สำคัญที่สุดใน Class
- สุดท้าย ผมเติม Method Body เพิ่มเติม Implementation Comment ตามต้องการ
- ขณะเขียน Method Body ผมมักจะค้นพบความจำเป็นของ Method และ Instance Variable เพิ่มเติม สำหรับ Method ใหม่แต่ละอัน ผมเขียน Comment Interface ก่อน Body ของ Method สำหรับ Instance Variable ผมเติม Comment ในเวลาเดียวกับที่ผมเขียน Variable Declaration
เมื่อโค้ดเสร็จแล้ว Comment ก็เสร็จแล้ว ไม่มี Backlog ของ Comment ที่ยังไม่เขียน
Approach Comments-First นี้มีประโยชน์สามอย่าง อย่างแรก มันสร้าง Comment ที่ดีกว่า ถ้าคุณเขียน Comment ขณะที่คุณออกแบบ Class ปัญหา Design หลักจะสดใจในใจของคุณ ดังนั้นจึงเป็นเรื่องง่ายในการบันทึกมัน ดีกว่าที่จะเขียน Comment Interface สำหรับแต่ละ Method ก่อน Body ของมัน เพื่อที่คุณสามารถมุ่งเน้นไปที่ Abstraction และ Interface ของ Method โดยไม่ถูกรบกวนโดย Implementation ระหว่างขั้นตอนการเขียนโค้ดและการ Test คุณจะสังเกตและแก้ไขปัญหากับ Comment คุณจะค้นพบแม้ว่า Comment ส่วนหนึ่งอาจต้องปรับปรุง ดังนั้น Comment จึงปรับปรุงในระหว่างการพัฒนา
15.3 Comment เป็น Design Tool
ประโยชน์ที่สอง และสำคัญที่สุด ของการเขียน Comment ตั้งแต่ต้น คือมันปรับปรุง System Design ของคุณ Comment เป็นวิธีเดียวในการจับ Abstraction อย่างสมบูรณ์ และ Good Abstraction นั้นเป็นพื้นฐานของ Good System Design ถ้าคุณเขียน Comment อธิบาย Abstraction ตั้งแต่ต้น คุณสามารถทบทวนและปรับแต่งพวกมันก่อนเขียน Implementation Code ในการเขียน Comment ที่ดี คุณต้องระบุสาระสำคัญของ Variable หรือ Code : สิ่งใดที่เป็นประเด็นที่สำคัญที่สุดของสิ่งนี้ สิ่งนี้สำคัญที่จะต้องทำตั้งแต่เร็วในขั้นตอน Design มิฉะนั้น คุณก็แค่ Hack Code
Comment ช่วยเป็น Canary ในเหมืองถ่านหินของความซับซ้อน ถ้า Method หรือ Variable ต้องการ Comment ยาว มันเป็น Red Flag ที่บ่งบอกว่าคุณไม่มี Good Abstraction หากจำไว้จาก บทที่ 4 ว่า Class ควรจะลึก: Class ที่ดีที่สุดมี Interface ที่ง่าย แต่ Implement Function ที่ทรงพลัง วิธีที่ดีที่สุดในการตัดสินความซับซ้อนของ Interface คือจาก Comment ที่อธิบายมัน ถ้า Comment Interface สำหรับ Method ให้ข้อมูลทั้งหมดที่จำเป็นในการใช้ Method และยังสั้นและง่ายด้วย มันบ่งชี้ว่า Method มี Simple Interface ในทางกลับกัน ถ้าไม่มีวิธีอธิบาย Method อย่างสมบูรณ์โดยไม่ Comment ที่ยาวและซับซ้อน ดังนั้น Method มี Complex Interface คุณสามารถเปรียบเทียบ Method's Interface Comment กับ Implementation เพื่อให้รู้สึกได้ว่า Method นั้นลึกแค่ไหน: ถ้า Interface Comment ต้องอธิบาย Feature หลักทั้งหมดของ Implementation ดังนั้น Method นั้นจึงเขินต่ำ ความคิดเดียวกันนี้ใช้ได้กับ Variable: ถ้าต้องใช้ Comment ยาวในการอธิบาย Variable อย่างสมบูรณ์ มันเป็น Red Flag ที่บ่งบอกว่าคุณอาจไม่ได้เลือก Variable Decomposition ที่ถูกต้อง โดยรวมแล้ว การเขียน Comment ช่วยให้คุณประเมินการตัดสินใจด้านการออกแบบของคุณตั้งแต่เร็ว เพื่อให้คุณสามารถค้นพบและแก้ไขปัญหา
Red Flag: ยากที่จะอธิบาย
Comment ที่อธิบาย Method หรือ Variable ควรจะง่ายและสมบูรณ์พร้อมกัน ถ้าคุณพบว่ายากที่จะเขียน Comment เช่นนั้น นั่นเป็นตัวบ่งชี้ว่าอาจมีปัญหากับ Design ของสิ่งที่คุณกำลังอธิบาย
แน่นอน Comment จะเป็น Good Indicator ของความซับซ้อนก็ต่อเมื่อพวกเขาสมบูรณ์และชัดเจน ถ้าคุณเขียน Method Interface Comment ที่ไม่ได้ให้ข้อมูลทั้งหมดที่จำเป็นในการ Invoke Method หรือ Comment ที่ลึกลับจนยากที่จะเข้าใจ ดังนั้น Comment ดังกล่าวจึงไม่ได้ให้ Measure ที่ดีของ Method's Depth
15.4 Early Comment เป็น Fun Comment
ประโยชน์ที่สาม และสุดท้าย ของการเขียน Comment ตั้งแต่เร็ว คือมันทำให้การเขียน Comment สนุก สำหรับผม หนึ่งในส่วนที่สนุกที่สุดของการเขียนโปรแกรมคือ Phase Design ตั้งแต่เร็ม สำหรับ Class ใหม่ โดยที่ผมออกแบบ Abstraction และ Structure สำหรับ Class Comment ของผมส่วนใหญ่เขียนในระหว่าง Phase นี้ และ Comment เป็นวิธีของผมในการบันทึกและ Test คุณภาพของการตัดสินใจด้าน Design ของผม ผมกำลังมองหา Design ที่สามารถแสดงออกมาอย่างสมบูรณ์และชัดเจนในคำเดียว Comment ที่ง่ายที่สุด Design ยิ่งดี ผมจึงรู้สึก Comment ที่ง่าย ดังนั้นการหา Comment ง่ายเป็นแหล่งความภาคภูมิใจ ถ้าคุณเขียนโปรแกรมอย่างมีกลยุทธ์ โดยเป้าหมายหลักของคุณคือ Great Design มากกว่าการเขียนโค้ดที่ใช้งานได้ ดังนั้นการเขียน Comment ควรจะสนุก เนื่องจากนั่นเป็นวิธีของคุณในการระบุ Design ที่ดีที่สุด
15.5 Early Comment มีค่าใช้จ่ายแพงหรือไม่
ตอนนี้เรามาทบทวนข้อโต้แย้งสำหรับการล่าช้าของ Comment กัน ซึ่งก็คือมันหลีกเลี่ยง Cost ของการปรับปรุง Comment เมื่อ Code พัฒนาไป การคำนวณอย่างง่ายจะแสดงว่านี่ไม่ได้ประหยัดมากนัก ก่อนอื่น ประมาณ Total Fraction ของ Development Time ที่คุณใช้ในการพิมพ์โค้ดและ Comment ด้วยกัน รวมถึง Time ในการปรับปรุง Code และ Comment ไม่น่าจะมากกว่าประมาณ 10% ของการพัฒนาทั้งหมด แม้ว่าครึ่งหนึ่งของ Total Code Line ของคุณเป็น Comment การเขียน Comment อาจจะไม่ร่วมมากกว่าประมาณ 5% ของ Total Development Time ของคุณ การล่าช้า Comment จนถึงจุดสิ้นสุดจะประหยัดเพียงเศษส่วนของสิ่งนี้เท่านั้น ซึ่งไม่มากนัก
การเขียน Comment ก่อนจะหมายความว่า Abstraction จะเสถียรมากขึ้นก่อนที่คุณจะเริ่มเขียน Code สิ่งนี้อาจประหยัด Time ในระหว่างการเขียนโค้ด ในทางตรงกันข้าม ถ้าคุณเขียน Code ก่อน Abstraction อาจจะพัฒนาไปเมื่อคุณเขียนโค้ด ซึ่งจะต้องการ Code Revision มากกว่า Comments-First Approach การพิจารณา Factor ทั้งหมดเหล่านี้ เป็นไปได้ว่า มันอาจจะเร็วกว่าโดยรวมในการเขียน Comment ก่อน
15.6 Conclusion
ถ้าคุณไม่เคยพยายามเขียน Comment ก่อน ลองดูสิ ติดไปกับมัน นานพอให้คุณคุ้นเคยกับมัน จากนั้นคิดว่ามันส่งผลกระทบต่อคุณภาพของ Comment ของคุณ คุณภาพของ Design ของคุณ และความสุขโดยรวมของคุณในการพัฒนา Software อย่างไร หลังจากที่คุณลองทำสิ่งนี้มาสักระยะหนึ่ง บอกให้ผมรู้ว่า ประสบการณ์ของคุณตรงกับประสบการณ์ของผมหรือไม่ และเพราะเหตุใด หรือเพราะเหตุใดจึงไม่