วิธีแนะนำรหัสให้กับเพื่อนร่วมงาน

คุณจะแนะนำเกี่ยวกับ codebase ซึ่งอาจจะค่อนข้างซับซ้อนและพันกันด้วย "gotchas" กับสมาชิกใหม่ในทีมของคุณได้อย่างไร

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

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

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

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

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

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

ขอบคุณ!

(เช่นเคยโปรดแก้ไขคำถามตามที่เห็นสมควร)

ขั้นตอนที่หนึ่งคือการลบ "gotchas" ออกจากรหัส รหัสที่ชัดเจนรัดกุมและสอดคล้องกันนั้นง่ายต่อการเข้าถึงทำงานและแก้ไขข้อบกพร่อง

คุณเริ่มจากที่ไหน

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

คุณจะครอบคลุมเทคโนโลยีหรือรูปแบบที่ไม่คุ้นเคยในส่วนของผู้ฟังโดยไม่ใช้เวลาทั้งวันได้อย่างไร

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

คุณผูกตรรกะทางธุรกิจกับโครงสร้างรหัสไว้ที่ไหน

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

สิ่งหนึ่งที่ต้องจำคือการทำให้คำสั่งสั้น คนมักจะเช็คเอาท์อย่างรวดเร็วดังนั้นการสอนเพิ่มเติม ณ จุดนั้นก็ไม่ 'ติด' แสดงสิ่งต่าง ๆ เป็นเวลา 15-60 นาที (ผู้คนต่างมีช่วงความสนใจต่างกัน) จากนั้นพัก 5-30 นาทีเพื่อให้พวกเขาประมวลผล

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

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

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

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

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

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

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

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

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

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

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