เอกสารย่อยสลาย - วิธีจัดการกับมัน?

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

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

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

โดยทั่วไปแล้วสิ่งที่เกี่ยวข้องกับการเขียนโค้ดที่ไม่เหมาะกับรหัสเอกสารทั่วไปเนื่องจากขนาดและลักษณะของบล็อก / บทความที่คล้ายกัน

ปัญหา

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

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

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

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

ความคิดเริ่มต้นของฉันคือการโยนมันลงในการให้อภัย (หลังจากฉันถูกกัดโดย "เคล็ดลับ" ที่ล้าสมัยสองสามครั้งติดต่อกัน) แต่ฉันคิดว่ามันอาจจะรุนแรงเกินไป ข้อมูลบางอย่างมีค่าน่าสังเกตและอ่านได้ดีในบางครั้ง แต่ปัญหายังคงเหมือนเดิม: คุณจัดการกับ"up-to-dateness" ได้อย่างไร? มันเชื่อมโยงกับซอร์สโค้ดอย่างใด (ดังนั้นเมื่อมีการตรวจสอบไฟล์เวอร์ชันที่อัปเดตแล้วผู้เขียนบทความจะได้รับแจ้งว่าเขาอาจต้องแก้ไขโค้ด / บทความ) มีบุคคลที่ได้รับมอบหมาย "คอยดูแล" เป็นประจำทุกวันหรือไม่? ทำความสะอาดปกติหรือไม่

ดูเหมือนว่าคุณกำลังบันทึกเรื่องไม่สำคัญในวิกิ

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

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

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

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

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

เอกสารควรได้รับการปฏิบัติเหมือนส่งมอบและอยู่ภายใต้กฎของการตรวจสอบย้อนกลับและการยอมรับรวมทั้งให้เวลาในการพัฒนาที่เหมาะสม

ไม่ใช่เรื่องแปลกที่จะเห็นคน "คาดหวัง" เอกสารซอฟต์แวร์ที่จะได้รับเมื่อมันไม่ได้

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

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

หากสิ่งที่เปลี่ยนแปลงอย่างรวดเร็วนั้นไม่ควรดูแลนอกโค้ด

แรงจูงใจเบื้องหลังการตัดสินใจออกแบบสำหรับบางส่วนของ API

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

ความเสื่อมโทรมตามปกติ รหัสมีการเปลี่ยนแปลงวิกิยังคงเหมือนเดิม

นี่คือที่ "เอกสารปฏิบัติการ" - การทดสอบหน่วย - มีประโยชน์มาก หากการเปลี่ยนแปลงรหัสและการทดสอบไม่เปลี่ยนแปลงไปพร้อมกับมันแล้วการสร้างการแบ่ง แน่นอนว่าการเขียนข้อสอบเป็นเอกสารต้องใช้ทักษะบางอย่าง แต่จะเขียนเอกสารภายนอก (ดี) ด้วย

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

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

หากคุณใช้ภาษา. net ให้ดูที่ ( Sandcastle ) ซึ่งใช้เอกสาร XML (/// ใน C #) และแปลงเป็นรูปแบบวิธีใช้ MSDN

รูปแบบรวมถึงคำอธิบายความคิดเห็นและมีความสามารถในการรวมตัวอย่างโค้ดรวมถึงคุณสมบัติอื่น ๆ คุณสามารถส่งออกในรูปแบบ. CHM, .HsX, .MSCH และ HTML / ASP.NET โปรเจ็กต์จริงถูกเพิ่มเข้ากับโซลูชันของคุณและสร้างขึ้นบนบิลด์เซิร์ฟเวอร์ เราได้ทำสิ่งนี้และนำไปใช้กับเว็บไซต์ทุกรุ่นและผู้บริโภคชื่นชอบเพราะเอกสารประกอบนั้นเกี่ยวข้องกับรุ่นและปรับปรุงอย่างต่อเนื่อง

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

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

ฉันจะมุ่งเน้นไปที่สองพื้นที่ 1) รหัส 2) บันทึกย่อและเอกสารที่ไม่มีรหัส

1) รหัส

พยายามทำให้เป็นเอกสารด้วยตนเอง ในอดีตฉันพบว่ามักได้รับคำแนะนำ แต่ไม่ค่อยอธิบายได้ดีดังนั้น ...

แทนที่จะเป็นโค้ดหลอกประเภทนี้:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

ทำรหัสที่มีลักษณะดังนี้:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

ใช้การควบคุมแหล่งที่มาเพื่อติดตามข้อมูล 'ใครทำอะไรเมื่อ'

2) ไม่ใช่รหัส

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