ความเกลียดชังต่อเอกสารในอุตสาหกรรมคืออะไร

ดูเหมือนจะมีความรังเกียจที่จะเขียนแม้แต่เอกสารพื้นฐานที่สุด READMEs โครงการของเราค่อนข้างเปลือยเปล่า ไม่มีรายการการอ้างอิงที่อัปเดตในเอกสาร

มีบางสิ่งที่ฉันไม่รู้ในอุตสาหกรรมที่ทำให้โปรแกรมเมอร์ไม่ชอบการเขียนเอกสารหรือไม่? ฉันสามารถพิมพ์ย่อหน้าของเอกสารได้ถ้าจำเป็นดังนั้นทำไมคนอื่นถึงเกลียดชังมัน

ที่สำคัญกว่าฉันจะโน้มน้าวพวกเขาได้อย่างไรว่าการเขียนเอกสารจะช่วยเราประหยัดเวลาและความยุ่งยากในอนาคต

ฉันไม่คิดว่ามันจะเป็นประโยชน์ในการคาดเดาเกี่ยวกับแรงจูงใจของคนที่ไม่ใช้สิ่งที่คุณคิดว่าเป็นแนวปฏิบัติที่ดีหรือผู้ที่ยังคงทำสิ่งที่คุณเห็นว่าเป็นการปฏิบัติที่ไม่ดี ในธุรกิจนี้คนที่ตกอยู่ในหนึ่งหรือทั้งสองประเภทเหล่านั้นจะไกลมีจำนวนมากกว่าคนที่คุณจะเห็นตาเพื่อตากับเพื่อหยุดทำให้ตัวเองบ้า

ให้เน้นที่ปัญหาและวิธีแก้ไขที่เป็นไปได้แทน

1. เขียนเอกสารที่ดีด้วยตัวคุณเอง

อาจไม่เป็นจริงที่จะคาดหวังว่าทุกคนในทีมของคุณจะนำความพยายามของพวกเขาไปยังสิ่งที่คุณเห็นว่าเป็นปัญหา โดยเฉพาะอย่างยิ่งถ้าคุณเป็นผู้มาใหม่กับทีม ฉันอยากเดาว่าคุณเป็นเพราะถ้าคุณเป็นสมาชิกผู้ก่อตั้งของทีมดูเหมือนว่าคุณจะสามารถแก้ไขปัญหานี้ได้ตั้งแต่ต้นแล้ว

ลองพิจารณาการทำงานเพื่อบรรลุเป้าหมายในการเขียนเอกสารที่ดีด้วยตัวคุณเองและให้คนอื่นใช้มันแทน ตัวอย่างเช่นถ้ามีคนในทีมของฉันถามฉันว่าซอร์สโค้ดสำหรับโครงการ A อยู่ที่ใดหรือการกำหนดค่าพิเศษใดที่โครงการ A ต้องการฉันจะชี้ให้พวกเขาไปที่หน้าโครงการวิกิ

หากมีคนถามฉันเกี่ยวกับวิธีเขียนการใช้งานใหม่ของ Factory F เพื่อกำหนดสิ่งสำหรับลูกค้า C ฉันจะบอกพวกเขาว่าในหน้า 10 ของคู่มือนักพัฒนา

นักพัฒนาส่วนใหญ่เกลียดการถามคำถามที่ทำให้พวกเขาดูเหมือนว่าพวกเขาไม่สามารถ "อ่านรหัส" มากกว่าที่พวกเขาเกลียดการอ่านเอกสารดังนั้นหลังจากตอบกลับในลักษณะนี้มากพอพวกเขาจะไปที่เอกสารก่อน

2. พิสูจน์คุณค่าของเอกสารของคุณ

ตรวจสอบให้แน่ใจว่าคุณใช้ทุกโอกาสในการชี้ให้เห็นว่าเอกสารมีการพิสูจน์คุณค่าของมัน (หรือจะใช้ถ้ามี) พยายามให้ละเอียดและหลีกเลี่ยง "ฉันบอกคุณแล้ว" แต่มันถูกต้องตามกฎหมายที่จะพูดสิ่งที่ชอบ

สำหรับการอ้างอิงในอนาคตหน้าวิกิของโครงการนี้มีข้อมูลเกี่ยวกับสาขาของรหัสหลักที่สร้างขึ้นเพื่อรองรับการปล่อย 2.1 อย่างต่อเนื่องดังนั้นในอนาคตเราสามารถหลีกเลี่ยงการทดสอบการถดถอยแบบเต็มหากผู้ที่ตรวจสอบรุ่นที่วางจำหน่าย วิกิก่อนที่จะตรวจสอบรหัส

หรือ

ฉันดีใจมากที่ฉันได้เขียนขั้นตอนสำหรับการทำภารกิจ T ฉันไม่สนใจจริงๆถ้าไม่มีใครใช้มัน - มันช่วยฉันได้มากกว่าเวลาที่ฉันใช้ในการเขียน

3. รับการจัดการบนกระดาน

หลังจากเกิดเหตุการณ์เล็ก ๆ น้อย ๆ ที่การมีเอกสารช่วยประหยัดเวลา / เงินคุณอาจสังเกตเห็น "การละลาย" ที่ชัดเจนต่อเอกสาร นี่คือเวลาที่จะกดจุดโดยเริ่มต้นที่จะรวมเวลาเอกสารในการประมาณของคุณ (แม้ว่าโดยปกติฉันมักจะปรับปรุง / สร้างเอกสารในขณะที่กระบวนการที่ยาวนานกำลังทำงานเช่นคอมไพล์หรือเช็คอิน) โดยเฉพาะอย่างยิ่งหากนี่คือการจ้างงานล่าสุดอาจเป็นไปได้ว่าสิ่งนี้จะไม่ถูกถาม แต่ถูกมองว่าเป็นการปฏิบัติแบบใหม่ที่คุณนำเข้ามาจากสถานที่ทำงานก่อนหน้า (ซึ่งอาจเป็นเช่นนั้น)

คำเตือน: ผู้บังคับบัญชาส่วนใหญ่ไม่ต้องการให้คนทำอะไรโดยเฉพาะอย่างยิ่งสิ่งที่ไม่เกี่ยวข้องโดยตรงกับงานที่เรียกเก็บเงินได้ดังนั้นอย่าคาดหวังว่าการสนับสนุนนี้จะอยู่ในรูปของเอกสาร แต่มีแนวโน้มที่จะให้บังเหียนอิสระแก่คุณมากกว่าที่จะเขียนเอกสารเพิ่มเติม

4. ส่งเสริมเอกสารเมื่อคุณเห็น

อาจเป็นส่วนหนึ่งของเหตุผลที่ผู้คนไม่ได้เขียนเอกสารบ่อยเท่าที่ควรเพราะพวกเขารู้สึกว่าไม่มีใครอ่านมัน ดังนั้นเมื่อคุณเห็นบางสิ่งที่คุณชอบอย่าลืมระบุว่าคุณดีใจที่มีให้

หากทีมของคุณทำการตรวจสอบโค้ดนี่เป็นเวลาที่คุณสามารถดรอปคำศัพท์หนึ่งหรือสองคำเพื่อกระตุ้นความคิดเห็นที่ดี

ขอบคุณสำหรับการบันทึกวิธีแก้ปัญหาสำหรับข้อผิดพลาด B ใน Framework G ฉันไม่ทราบเกี่ยวกับสิ่งนั้นและฉันไม่คิดว่าฉันจะเข้าใจสิ่งที่คุณกำลังทำอยู่หากไม่มีสิ่งนั้นในนั้น

หากคุณมีใครบางคนในทีมที่กระตือรือร้นเกี่ยวกับเอกสารจริง ๆมันไม่เจ็บที่จะปลูกฝังบุคคลนั้นผ่านการไปทานอาหารกลางวันหรือดื่มกาแฟและตรวจสอบให้แน่ใจว่ามีการตรวจสอบเพียงเล็กน้อยเพื่อต่อต้านการท้อแท้ที่พวกเขาอาจได้รับ ไม่ให้ความสำคัญกับเอกสารมากนัก

นอกเหนือจากนั้นมันไม่ใช่ปัญหาของคุณเว้นแต่คุณจะอยู่ในตำแหน่งผู้นำหรือผู้บริหาร คุณสามารถพาม้าขึ้นน้ำ แต่ไม่สามารถดื่มได้ หากไม่ใช่ม้าของคุณคุณอาจไม่มีความสุขที่กระหายน้ำ แต่สิ่งที่คุณทำได้คือเติมน้ำในราง

มีสองปัจจัยหลักในประสบการณ์ของฉัน:

กำหนดเวลา

บริษัท ส่วนใหญ่ได้รับการผลักดันให้วันที่ QA หนี้เทคโนโลยีและการออกแบบที่แท้จริงถูกตัดเพียงเพื่อให้ผู้จัดการโครงการไม่ได้ดูไม่ดีหรือมีกำหนดส่งงานลูกค้าตามสัญญาที่ไร้สาระ ในสภาพแวดล้อมนี้ที่แม้แต่คุณภาพการใช้งานถูกตัดออกไปการลงทุนระยะยาวเช่นเอกสารมีโอกาสน้อยมาก

เปลี่ยนแปลง

แนวปฏิบัติที่ดีที่สุดที่ค่อนข้างใหม่สำหรับนักพัฒนาคือการไม่เน้นความคิดเห็น แนวคิดก็คือการเก็บข้อมูลไว้ในที่เดียว (รหัส [รวมถึงการทดสอบ] และความคิดเห็นรอบ ๆ รหัส) นำไปสู่ค่าใช้จ่ายจำนวนมากในการทำให้ข้อมูลตรงกันเพื่อผลประโยชน์เพียงเล็กน้อย "หากโค้ดของคุณอ่านยากจนคุณต้องการความคิดเห็นคุณจะไม่ต้องเสียเวลาทำความสะอาดโค้ดเลย"

โดยส่วนตัวฉันจะไม่ดูความคิดเห็นอีกต่อไป รหัสไม่สามารถโกหกได้

เอกสารอ้างอิงหลอดเลือดดำเดียวกัน ด้วยการยอมรับอย่างรวดเร็วของความคล่องตัวผู้คนต่างยอมรับว่าข้อกำหนดมีการเปลี่ยนแปลงอย่างสม่ำเสมอ ด้วยการใช้อย่างแพร่หลายของการเปลี่ยนโครงสร้างองค์กรของโค้ดจะเปลี่ยนไปค่อนข้างมาก เหตุใดจึงต้องใช้เวลาในการบันทึกสิ่งเหล่านี้ทั้งหมดที่ผูกพันกับการเปลี่ยนแปลง รหัสและการทดสอบควรทำผลงานได้ดีพอ

มีหลายปัจจัยในการเล่นที่นี่:

1. รหัสที่เขียนดีเป็นเอกสารของตัวเอง สิ่งอื่น ๆ ที่เท่าเทียมกันนั้นดีกว่าที่จะเขียนโค้ดที่ชัดเจนซึ่งพูดด้วยตัวเองแทนที่จะเป็นเอกสารเพิ่มเติม ทำเช่นนั้นและคุณจะต้องแก้ไขเอกสารน้อยลงเมื่อคุณเปลี่ยนรหัสนั้น

2. การเขียนเอกสารเป็นทักษะที่แตกต่างจากการเขียนรหัส นักพัฒนาซอฟต์แวร์บางคนเก่งกว่าคนอื่น บางคนเขียนโค้ดได้ดีกว่าเขียนเอกสารบ้าง

3. เอกสารจะต้องถูกเขียนเพียงครั้งเดียวไม่ใช่สองครั้ง (หนึ่งครั้งในซอร์สโค้ดและอีกครั้งในคำแนะนำของโปรแกรมเมอร์) นั่นเป็นเหตุผลที่เรามีสิ่งต่าง ๆ เช่นความคิดเห็น XML และเครื่องกำเนิดเอกสาร น่าเสียดายที่การใช้เครื่องมือดังกล่าวอาจยุ่งยากและยุ่งยากกว่าการเขียนเอกสารด้วยมือซึ่งเป็นเหตุผลว่าทำไมคุณไม่เห็นเครื่องมือเหล่านี้ที่ใช้กันอย่างแพร่หลาย

4. เอกสารที่ดีใช้เวลานานและทำได้ยาก สิ่งอื่น ๆ ที่เท่าเทียมกันอาจมีค่ามากกว่าในการเขียนรหัสใหม่กว่าการเขียนเอกสารสำหรับรหัสที่มีอยู่แล้ว

5. เมื่อรหัสเปลี่ยนแปลงคุณต้องเปลี่ยนเอกสาร เอกสารที่น้อยลงมีน้อยที่จะต้องมีการเปลี่ยนแปลง

6. ยังไม่มีใครอ่านเอกสารอยู่แล้วทำไมต้องกังวล

ช้างในห้อง: โปรแกรมเมอร์ไม่ใช่นักเขียน (จำเป็น) และพวกเขาไม่จำเป็นต้องคล้อยตามการใช้งานของพวกเขากับนักเขียนทางเทคนิค ช้างตัวที่สองในห้อง: นักเขียนด้านเทคนิคโดยทั่วไปจะไม่สามารถหารายละเอียดที่เป็นประโยชน์สำหรับนักพัฒนาในอนาคต (แม้ว่านักพัฒนาจะยอมอธิบายให้พวกเขาเข้าใจ)

ระบบที่ซับซ้อนสามารถเกิดความไม่น่าไว้วางใจได้เมื่อเวลาผ่านไปโดยไม่มีเอกสารประกอบที่เหมาะสม รหัสจะมีค่าน้อยกว่าแปรผกผันกับความละเอียดของมัน [sic] ฝ่ายบริหารได้รับการว่าจ้างวิศวกรซอฟต์แวร์ที่สามารถอ่านรายละเอียดรหัสและเล้าโลมจากนักพัฒนาจ่ายให้เขาตามอัตราของนักพัฒนาและสั่งให้เขาจัดทำเอกสารและดูแลรักษาเอกสาร ผู้เขียนคนนี้สามารถอ่านรหัสและจะรู้ว่าคำถามที่จะถามและจะกรอกรายละเอียดตามความจำเป็น เช่นเดียวกับคุณมีแผนกควบคุมคุณภาพคุณมีแผนกเอกสารภายใน

รหัสจะมีค่ามากขึ้นเนื่องจากคุณสามารถให้สิทธิ์แก่บุคคลที่สาม (เพราะเขาเข้าใจได้) รหัสสามารถตรวจสอบได้ง่ายขึ้นและปรับปรุง / ปรับปรุงใหม่อีกครั้ง แยกซอฟต์แวร์รุ่นที่มีน้ำหนักเบามากขึ้นและคุณจะสามารถแนะนำนักพัฒนาใหม่เข้าสู่โครงการได้ง่ายขึ้นวิศวกรฝ่ายสนับสนุนของคุณจะรักที่จะทำงานให้คุณ

สิ่งนี้จะไม่เกิดขึ้น

ที่สำคัญกว่าฉันจะโน้มน้าวพวกเขาได้อย่างไรว่าการเขียนเอกสารจะช่วยเราประหยัดเวลาและความยุ่งยากในอนาคต

มันทำอย่างนั้นเหรอ?

เอกสารมีสองประเภท:

เอกสารที่เป็นประโยชน์

เอกสารวิธีใช้ผลิตภัณฑ์สำเร็จรูป, API, ที่อยู่ IP หรือชื่อ URL ที่เซิร์ฟเวอร์ของเรามีเป็นต้นโดยทั่วไปทุกอย่างที่ใช้งานหนักและเป็นประจำทุกวัน ข้อมูลผิดจะถูกค้นพบอย่างรวดเร็วและจะได้รับการแก้ไข ความต้องการจะพบได้ง่ายและง่ายต่อการแก้ไข (เช่น Wiki ออนไลน์)

เอกสารที่ไร้ประโยชน์

เอกสารที่เปลี่ยนแปลงบ่อยคนน้อยมากที่สนใจและไม่มีใครรู้ว่าจะหามันได้ที่ไหน เช่นเดียวกับสถานะปัจจุบันของสถานที่ที่มีการใช้งาน หรือเอกสารความต้องการในเอกสารคำที่ซ่อนอยู่ที่ไหนสักแห่งใน SVN อัปเดตเมื่อ 3 ปีที่แล้ว เอกสารนี้จะใช้เวลาในการเขียนและเวลาในการตรวจสอบว่ามันผิดในภายหลัง คุณไม่สามารถพึ่งพาเอกสารประเภทนี้ได้ มันไร้ประโยชน์ มันเสียเวลา

โปรแกรมเมอร์ไม่ชอบเขียนหรืออ่านเอกสารที่ไร้ประโยชน์ แต่ถ้าคุณสามารถแสดงเอกสารซึ่งมีประโยชน์พวกเขาจะเขียนมัน เราประสบความสำเร็จในโครงการสุดท้ายของฉันเมื่อแนะนำ Wiki ซึ่งเราสามารถเขียนข้อมูลทั้งหมดที่เราต้องการได้บ่อยครั้ง

ฉันจะบอกว่าเหตุผลหลักคือการขาดพินัยกรรมและขาดความเข้าใจในการทำงานของเอกสาร เอกสารที่ต้องพิจารณามีหลายประเภท:

เอกสารประกอบผลิตภัณฑ์ / การเปิดตัว

นี่คือสิ่งที่ออกไปพร้อมกับผลิตภัณฑ์ 'เสร็จสิ้น' ของคุณ นี่เป็นมากกว่าคู่มือการใช้งานนี่คือ READMEs บันทึกการเปลี่ยนแปลงวิธีการใช้และสิ่งที่คล้ายกัน ในทางทฤษฎีคุณสามารถหนีไปได้โดยไม่ต้องเขียนสิ่งเหล่านี้ แต่คุณจบลงด้วยผลิตภัณฑ์ที่ผู้คนไม่ต้องการใช้หรือภาระการสนับสนุนที่มีราคาแพงโดยไม่จำเป็น

เอกสาร API

สิ่งนี้อธิบายบางสิ่งที่ควรจะค่อนข้างคงที่ เนื่องจากผู้บริโภคจำนวนมากอาจใช้รหัส API ของคุณจึงควรมีความเสถียรเพียงพอที่ร้อยแก้วที่อธิบายวิธีการใช้มีค่า อธิบายถึงพารามิเตอร์ที่ได้รับการสนับสนุนสิ่งที่สามารถส่งคืนค่าได้และข้อผิดพลาดใดที่อาจทำให้ผู้ใช้รายอื่นสามารถเข้าใจ API ของคุณในระดับที่ถูกต้องของนามธรรม - อินเทอร์เฟซ ( ไม่ใช่การนำไปใช้)

รหัสความคิดเห็น

ความคิดเห็นของอุตสาหกรรมเกี่ยวกับความคิดเห็นดูเหมือนว่าจะอยู่ในฟลักซ์ในขณะนี้ เมื่อฉันเริ่มเขียนโค้ดอย่างมืออาชีพความคิดเห็นนั้นเป็นงานที่ไม่เกี่ยวกับการเขียนโค้ด ตอนนี้แฟชั่นคือการเขียนรหัสที่ชัดเจนดังนั้นความคิดเห็นที่ไม่จำเป็น ฉันคาดเดาได้ว่านี่เป็นส่วนหนึ่งเนื่องจากภาษาที่ทันสมัยจำนวนมากถูกเขียนในระดับที่สูงกว่ามากและเป็นวิธีที่ง่ายกว่าในการเขียนรหัสที่อ่านง่ายใน Java, JavaScript, Ruby และอื่น ๆ กว่าในแอสเซมเบลอร์ , C, FORTRAN ฯลฯ ดังนั้นความคิดเห็นมีค่ามากขึ้น

ฉันยังคงเชื่อว่ามีค่าในความคิดเห็นที่อธิบายถึงความตั้งใจของส่วนของรหัสหรือรายละเอียดบางอย่างเกี่ยวกับสาเหตุที่เลือกอัลกอริทึมบางอย่างให้ชัดเจนยิ่งขึ้น ไม่จำเป็นต้องแก้ไขจริง)

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

นี่คือสองเซ็นต์ของฉัน

1. แถลงการณ์เปรียวระบุว่า"ซอฟต์แวร์ที่ใช้งานได้บนเอกสารที่ครอบคลุม"และไม่ใช่ทุกคนที่อ่านเพื่อเข้าถึง"นั่นคือในขณะที่มีค่าในรายการทางด้านขวา

2. น่าเสียดายที่เป็นเรื่องปกติที่จะhttps://en.wikipedia.org/wiki/Code_and_fixและเอกสารไม่ทำงานกับรุ่นนี้ (ไม่ซิงค์)

3. อุตสาหกรรมการพัฒนาซอฟต์แวร์ไม่ได้รับการควบคุม ไม่มีข้อกำหนดทางกฎหมายในการเขียนเอกสาร

4. รหัสเอกสารด้วยตนเองเป็นแนวโน้มปัจจุบัน

ต้องบอกว่าฉันคิดว่ามีเอกสารที่ดีออกมามากมาย

เอกสารต้องใช้เวลาและฉันสงสัยว่านักพัฒนาจำนวนมากมีการเรียกใช้เอกสารมากเกินไปซึ่งแย่กว่าไร้ประโยชน์ พวกเขาเข้าใจว่าไม่เพียง แต่เอกสารจะทำให้พวกเขาเดือดร้อนจากผู้จัดการของพวกเขา (คนเดียวที่คอยตัดส่วน QA ของตาราง) แต่มันจะไม่ช่วยใครรวมถึงพวกเขาด้วย

เอกสารที่เหมาะสมครึ่งหนึ่งคือการลงทุนในอนาคต หากคุณไม่สนใจอนาคต (เพราะคุณไม่ได้คิดนอกเรื่องเงินเดือนต่อไปหรือเพราะคุณคิดว่ามันจะไม่เป็นปัญหาของคุณ) แสดงว่าการคิดทำเอกสารนั้นเจ็บปวดมาก

การตอบสนองอื่น ๆ จำนวนมากฉาบกว่าจุดที่มีเอกสารอย่างน้อยสองประเภท: ชุดหนึ่งสำหรับนักพัฒนาอื่น ๆ และชุดอื่นสำหรับผู้ใช้ปลายทาง คุณอาจต้องการเอกสารเพิ่มเติมสำหรับผู้ดูแลระบบผู้ติดตั้งและเจ้าหน้าที่ฝ่ายช่วยเหลือทั้งนี้ขึ้นอยู่กับสภาพแวดล้อมของคุณ กลุ่มเป้าหมายแต่ละกลุ่มมีความต้องการและระดับความเข้าใจที่แตกต่างกัน

พิจารณานักพัฒนาทั่วไป (สเตอริโอ -): เขาเป็นผู้เขียนโค้ดโดยเลือก เขาเลือกอาชีพออกจากสายตาสาธารณะและใช้เวลานานหลายชั่วโมงหลังคีย์บอร์ดในการสื่อสารกับตัวเขาเป็นหลัก กระบวนการของเอกสารเป็นรูปแบบของการสื่อสารและชุดทักษะที่จำเป็นในการผลิตเอกสารที่ดีนั้นตรงกันข้ามกับทักษะที่จำเป็นในการสร้างรหัสที่ดี

นักเขียนเอกสารที่ดีสามารถสื่อสารได้หลายภาษา: ภาษาของผู้ใช้, ภาษาของการจัดการ, ภาษาของพนักงานให้ความช่วยเหลือ, ภาษาของนักพัฒนา มันเป็นหน้าที่ของนักเขียนเอกสารที่จะเข้าใจสิ่งที่ coder สื่อสารและแปลว่าเป็นรูปแบบที่ทุกกลุ่มสามารถเข้าใจได้

เมื่อคุณคาดว่าโคเดอร์เพื่อพัฒนาทักษะที่จำเป็นในการเป็นนักสื่อสารที่ดี (เป็นลายลักษณ์อักษรหรืออย่างอื่น) ระยะเวลาที่ใช้ในการสร้างชุดทักษะหลัก (การเข้ารหัส!) จะลดลง ยิ่งเขาได้รับมากขึ้นจากเขตความสะดวกสบายของเขา (การเข้ารหัสและการสื่อสารกับ coders อื่น ๆ ) ยิ่งต้องใช้เวลาและพลังงานมากขึ้นในการทำงานให้ดีขึ้น คุณสามารถคาดหวังได้อย่างสมเหตุสมผลว่าผู้ให้บริการมืออาชีพต้องการที่จะมุ่งเน้นไปที่ความสามารถหลักของเขาเป็นหลัก

ด้วยเหตุนี้เอกสารประกอบ (ยกเว้นความคิดเห็นแบบอินไลน์โค้ด) เป็นสิ่งที่ดีที่สุดสำหรับนักสื่อสารไม่ใช่ผู้เขียนโค้ด

การอ่านรหัสแสดงให้คุณเห็นว่ามันทำงานอย่างไร ไม่สามารถอธิบายได้ว่าทำไม : คุณต้องการความคิดเห็น

การอ่านรหัสจะแสดงชื่อของวิธีการและประเภทของพารามิเตอร์ ไม่สามารถอธิบายความหมายหรือเจตนาที่แท้จริงของผู้แต่ง: คุณต้องการความคิดเห็น

ความคิดเห็นไม่ได้แทนที่การอ่านรหัสพวกเขาเพิ่มไป

เอกสารไม่ถูกดำเนินการตามรหัสคือ ดังนั้นมักจะไม่มีข้อเสนอแนะที่มีประสิทธิภาพในการตรวจสอบว่าเอกสารอยู่ในสถานที่และสมบูรณ์ นี่คือเหตุผลเดียวกันกับที่ความคิดเห็นของรหัสมีแนวโน้มที่จะเน่า

Donald Knuth ส่งเสริมการเขียนโปรแกรมวรรณกรรมเพื่อปรับปรุงคุณภาพของซอฟต์แวร์เขียนเอกสารด้วยรหัสได้อย่างมีประสิทธิภาพ ฉันเคยเห็นโครงการไม่กี่แห่งที่ใช้วิธีนี้ค่อนข้างมีประสิทธิภาพ

โดยส่วนตัวแล้วฉันพยายามที่จะยึดถือแนวโน้มที่ทันสมัยของการรักษา API สาธารณะของรหัสของคุณให้อ่านได้มากที่สุดและใช้การทดสอบหน่วยเพื่อใช้เอกสารสำหรับนักพัฒนาอื่น ๆ ฉันคิดว่านี่เป็นส่วนหนึ่งของแนวคิดที่ใหญ่กว่าของการมี API ของคุณในรูปแบบที่สามารถสำรวจและค้นพบได้ ฉันคิดว่าวิธีการนี้เป็นส่วนหนึ่งของสิ่งที่HATEOASพยายามที่จะประสบความสำเร็จกับบริการเว็บ

ประเด็นเล็ก ๆ น้อย ๆ แต่สิ่งหนึ่งที่ดูเหมือนจะมีความสำคัญกับนักพัฒนาบางคนที่เขียนเอกสารเล็ก ๆ น้อย ๆ น่ารังเกียจพวกเขาไม่สามารถพิมพ์ได้ หากคุณมีการประมาณของระบบ 10 นิ้วคุณมักจะเขียนเอกสารเพิ่มเติมเพียงเพราะมันง่าย แต่ถ้าคุณติดกับการล่าสัตว์และการจิกคุณจะหายไป ถ้าฉันต้องรับผิดชอบในการจ้างงานนี่เป็นสิ่งที่ฉันจะตรวจสอบ

ผู้ที่ไม่ชอบอ่านเอกสารไม่ชอบเขียนเอกสาร โปรแกรมเมอร์จำนวนมากจะทำทุกอย่างเท่าที่ทำได้เพื่อหลีกเลี่ยงการอ่านเอกสารอย่างละเอียด

อย่ามุ่งเน้นการเขียนเน้นการอ่าน เมื่อโปรแกรมเมอร์อ่านเอกสารและรวบรวมสิ่งต่าง ๆ จากมันพวกเขาจะเห็นคุณค่าและมีแนวโน้มที่จะเขียนมากขึ้น

เมื่อฉันเริ่มงานปัจจุบันของฉันและรับโครงการฮาร์ดแวร์ + ซอฟต์แวร์จากคนที่เคยทำงานเกี่ยวกับเรื่องนี้มาก่อนฉันได้รับเอกสารคำประมาณร้อยหน้าเพื่ออธิบายระบบ ต้องใช้เวลาหลายวันในการผลิต ฉันดูมันอาจจะสองครั้ง แม้จะมีข้อมูลจำนวนมหาศาลอยู่ในนั้น แต่ก็ไม่ค่อยตอบคำถามจริง ๆ ที่ฉันมีเกี่ยวกับระบบและถึงแม้ว่ามันจะเป็นเช่นนั้น แต่ก็เร็วกว่าที่จะดูรหัส

หลังจากมีประสบการณ์อย่างเพียงพอคุณก็เริ่มที่จะคิดว่าทำไมต้องรำคาญ? ทำไมใช้เวลาตอบคำถามที่คนไม่เคยถาม คุณเริ่มตระหนักถึงความยากลำบากอย่างแท้จริงในการทำนายว่าข้อมูลใดที่ผู้คนจะค้นหาในเอกสารประกอบ มันเต็มไปด้วยข้อเท็จจริงที่หลีกเลี่ยงไม่ได้ไร้ประโยชน์ชัดเจนหรือไม่ชัดเจนและขาดคำตอบสำหรับคำถามเร่งด่วนที่สุด โปรดจำไว้ว่าการจัดทำเอกสารที่มีประโยชน์เป็นความพยายามในการทำนายพฤติกรรมของมนุษย์ เช่นเดียวกับการออกแบบส่วนต่อประสานผู้ใช้ที่ไม่น่าจะประสบความสำเร็จก่อนที่จะผ่านการทดสอบซ้ำและการดีบักหลายครั้งดังนั้นจึงไร้เดียงสาที่จะคิดว่ามันเป็นไปได้ที่จะเขียนเอกสารที่มีประโยชน์ตามความคาดหวังของผู้คน บทบาทเอกสารและภาษาในการตีความนั้น

ฉันมักจะคิดว่าส่วนใหญ่ของความกดดันที่จะเขียนเอกสารเกิดขึ้นจากความจริงที่ว่ามันเป็นงานบ้านที่ไม่พึงประสงค์และผู้คนชอบที่จะชักจูงซึ่งกันและกันในการทำงานบ้านที่ไม่พึงประสงค์ ("คุณไม่ได้กิน

อย่างไรก็ตาม

ฉันไม่คิดว่าเอกสารเป็นสิ่งที่สิ้นหวังในทุกด้าน ฉันคิดว่ามันสิ้นหวังเป็นหลักเมื่อผู้คนมองเอกสารเป็นภาระพิเศษที่ต้องทำให้สำเร็จก่อนที่งานจะเสร็จเพราะงานล้างข้อมูลชิ้นสุดท้ายต้องรีบผ่านและเป็นกล่องที่ต้องตรวจสอบ เอกสารเป็นสิ่งที่คุณควรทำงานในแง่มุมของวันที่คุณทำอยู่เสมอ ฉันคิดว่าอีเมลเป็นวิธีที่ดีในการทำเอกสาร เมื่อคุณเพิ่มคุณสมบัติใหม่เขียนอีเมลสั้น ๆ สองสามคนเพื่อบอกว่ามันคืออะไร เมื่อวาดแผนผังใหม่ให้สร้าง PDF และส่งให้กับทุกคนที่อาจสนใจ ข้อดีของอีเมลคือ:

1. คนมักจะตรวจสอบอีเมลในขณะที่ไม่มีใครลุยผ่านโฟลเดอร์ที่เรียกว่า "doc"

2. อีเมลมีอยู่ในบริบทแวดล้อมไปด้วยอีเมลอื่น ๆ ที่พูดถึงคุณลักษณะและคุณสมบัติที่เกี่ยวข้องและสิ่งอื่น ๆ ที่เกิดขึ้นในเวลานั้น

3. อีเมลสั้นและเน้นและมีหัวเรื่อง

4. อีเมลช่วยให้ผู้ที่สนใจถามคำถามได้ทันที

5. อีเมลสามารถค้นหาได้สูงเนื่องจากมีผู้ใช้ทุกอย่างและไคลเอนต์อีเมลมีระดับขั้นสูงในช่วงหลายปี

6. หากอยู่ในอีเมลบุคคลอื่นอย่างน้อยหนึ่งคนรู้ว่าจะหาได้จากที่ไหน

ในทางทฤษฎีแล้วดูเหมือนว่าความคิดเห็นในรหัสควรเป็น "แง่มุมของวันที่คุณทำอยู่เสมอ" แต่ด้วยความซื่อสัตย์ฉันไม่เคยอ่านความคิดเห็นในรหัส ฉันไม่แน่ใจว่าทำไม แต่พวกเขาไม่ได้เป็นประโยชน์มากอาจเป็นเพราะมีบริบทที่ไม่มีอีเมลที่จะแก้ปัญหา