Cách giới thiệu mã cho đồng nghiệp

Làm thế nào để bạn giới thiệu về codebase, có thể khá phức tạp và rối rắm với rất nhiều "gotchas" cho một thành viên mới trong nhóm của bạn?

Tôi nghĩ cách dễ nhất là kiến ​​trúc tổng thể được trình bày bằng sơ đồ và mất một vài tuần (hoặc vài tháng) để cung cấp cho người mới các nhiệm vụ được xác định rõ (và có phạm vi tốt) khi anh ta quen với mã hơn.

Tuy nhiên, với tư cách là một nhà tư vấn (và nhân viên cơ sở, tại đó,) tôi không thể luôn có điều đó do hạn chế về thời gian hoặc chỉ định vai trò nhóm. (Tôi đã ở trong dự án cụ thể này lâu gấp đôi so với bất kỳ ai khác, vì vậy "junior" không có cách nào "biết ít về mã / dự án.")

Bây giờ tôi đã được giao nhiệm vụ khá nhiều lần để giới thiệu một thành viên mới cho dự án và mã, và thật buồn là mỗi lần tôi thấy tôi không giỏi hơn nó nhiều so với trước đây. Tôi thích sơ đồ và hình ảnh, nhưng thường cảm thấy rằng chúng không giải thích thỏa đáng cho sự phức tạp trong một hệ thống. (Điều gì về tất cả các "gotchas" nhỏ?)

Dự án đang đi đến điểm mà chúng tôi sẽ bàn giao cho khách hàng, và để khiến mọi thứ trở nên khó khăn hơn, người mà tôi sẽ thực hiện chuyển giao kiến ​​thức về cơ bản chỉ là học đại học. (Không phải là tôi tốt hơn nhiều khi thực hiện chuyển giao kiến ​​thức với các nhà phát triển cao cấp.)

Tôi tham dự một nhóm người dùng mỗi tháng một lần và các cơ hội khác khi chúng phát sinh, vì vậy tôi không quen với việc được giới thiệu các chủ đề mới, nhưng cảm thấy khả năng của tôi để nhân rộng việc chia sẻ kiến ​​thức hiệu quả không đủ.

Bất kỳ lời khuyên sẽ được đánh giá rất cao. Tôi đang tìm kiếm chủ yếu cho một hướng dẫn tôi có thể làm theo. Ví dụ: Bạn bắt đầu từ đâu? Làm thế nào để bạn tiến hành? Làm thế nào để bạn bao quát các công nghệ hoặc mẫu lạ lẫm trên phần của người nghe mà không mất cả ngày? Nơi nào bạn ràng buộc trong logic kinh doanh so với cấu trúc mã?

Cảm ơn bạn!

(Như mọi khi, xin vui lòng chỉnh sửa câu hỏi khi bạn thấy phù hợp.)

Bước một là tất nhiên để loại bỏ "gotchas" khỏi mã. Mã rõ ràng, ngắn gọn, nhất quán sẽ dễ dàng truy cập, làm việc và gỡ lỗi hơn.

Bạn bắt đầu từ đâu

Tôi hỏi người mới về cách họ muốn vào codebase. Mọi người học khác nhau. Một số người thích có ít nhiệm vụ để làm việc. Một số như gỡ lỗi mã hiện có. Một số muốn xem mã đang chạy để hiểu những gì nó làm. Một số muốn bắt đầu tại điểm vào và chỉ cần điều hướng xung quanh. Một số muốn có sơ đồ thị giác ... Không có mẫu thiết lập nào sẽ hoạt động tốt nhất cho tất cả mọi người.

Làm thế nào để bạn bao quát các công nghệ hoặc mẫu lạ lẫm trên phần của người nghe mà không mất cả ngày?

Tôi tránh chúng. Hãy để chúng là hộp đen cho đến khi người mới hỏi về chúng. Sau đó cung cấp vừa đủ thông tin để có được ý chính của nó, với gợi ý rằng họ có thể tìm hiểu thêm về thời gian của mình hoặc hỏi sau khi công cụ chung được biết đến nhiều hơn.

Nơi nào bạn ràng buộc trong logic kinh doanh so với cấu trúc mã?

Tôi cố gắng không. Hầu như người mới học nên tự học tốt hơn để nó nằm trong tâm trí họ theo một cấu trúc tự nhiên hơn theo cách suy nghĩ của họ.

Một điều cần nhớ là giữ cho hướng dẫn ngắn. Mọi người có xu hướng kiểm tra khá nhanh, vì vậy, bất kỳ hướng dẫn nào vào thời điểm đó chỉ không 'dính'. Chỉ cho họ mọi thứ trong 15-60 phút (những người khác nhau có các khoảng chú ý khác nhau) sau đó nghỉ 5-30 phút để họ xử lý.

Theo kinh nghiệm của tôi, một cách tốt để thu hẹp khoảng cách giữa tổng quan rộng, sơ đồ kiến ​​trúc đưa ra và các chi tiết khó hiểu khi thực sự làm việc với mã là thực hiện một hệ thống sâu, tức là điều gì xảy ra khi có yêu cầu đến (đối với mã máy chủ ) hoặc người dùng tạo một đầu vào (cho mã máy khách), sau đó từng bước giải thích tất cả các lớp mã có liên quan.

Một cách khác là "tham quan có hướng dẫn" của mã nguồn, tức là đi qua các gói / không gian tên / mô-đun / thư mục và giải thích những gì mã trong mỗi chúng nói chung. Tất nhiên điều này đòi hỏi mã phải được đặt ra một cách hợp lý.

Bạn không dạy họ cơ sở mã, bạn đang dạy họ công việc của bạn . Đừng cố nghĩ những gì họ có thể cần, hãy nhìn vào những gì bạn thực sự cần biết khi làm công việc của bạn.

Kéo dài vài tháng qua của lịch sử theo dõi lỗi, câu chuyện người dùng scrum, báo cáo trạng thái và cam kết kiểm soát nguồn. Những tập tin bạn đã chạm vào nhiều nhất? Mã nào có vấn đề nhất? Nhiệm vụ nào đưa bạn lâu nhất? Rất có thể, nếu bạn không chạm vào nó trong vài tháng qua, điều đó không quan trọng như bạn nghĩ.

Nhìn vào chồng các bản in trên bàn của bạn. Kiểm tra lịch sử trình duyệt gần đây của bạn. Tìm kiếm các email đã lưu mà bạn đề cập đến thường xuyên, danh bạ bạn sử dụng, tài liệu bạn đã tải xuống. Một số tài liệu tham khảo hữu ích nhất mà tôi đã truyền cho người khác là những ghi chú tôi giữ cho riêng mình khi lần đầu tiên học hoặc thiết kế hệ thống. Tài liệu tham khảo nào hữu ích nhất cho bạn ?

Tiếp theo kéo lên tồn đọng đã biết của bạn. Những thứ bạn cần nghiên cứu để hoàn thành những nhiệm vụ đó? Những lĩnh vực mã nào có khả năng nhất chứa vấn đề? Truyền đạt thông tin đó như thể bạn đang ghi chú cho chính mình.

Nếu bạn tham khảo biểu đồ hoặc sơ đồ trong công việc hàng ngày của bạn, hãy bao gồm những biểu đồ. Nếu bạn chưa bao giờ bận tâm làm một cái, có lẽ nó sẽ không hữu ích cho người kế nhiệm / đồng nghiệp của bạn.

Một trong những nhiệm vụ khó khăn nhất khi giảng dạy là cố gắng đặt mình vào vị trí của họ. Trong trường hợp này, bạn đang ở trong đôi giày của họ. Tận dụng tối đa của nó.

Công việc hỗ trợ là tốt nhất, khắc phục một lỗi dễ dàng và đưa chúng đi qua các khu vực nơi nó sẽ được tìm thấy. họ sẽ nhanh chóng tìm hiểu làm thế nào mã phù hợp với nhau. Đương nhiên, họ sẽ đến để đặt câu hỏi về lỗi này và cơ sở mã, nhưng họ sẽ đến đó (và bạn sẽ sửa lỗi). Thông thường, việc tìm ra mọi thứ với các ví dụ sẽ dễ dàng hơn nhiều, tương tự, việc tìm ra một cơ sở mã dễ dàng hơn bằng cách chạy qua nó trong trình gỡ lỗi.

Nếu bạn không chắc chắn về các thay đổi mã (hoặc chúng là, thông thường tôi không chắc chắn về các sửa lỗi mã của mình cho đến khi tôi quen thuộc với cơ sở mã) thì bạn có thể xem lại trước khi đăng ký.

Tất nhiên, ý tưởng hiện tại của bạn về tổng quan rộng và sơ đồ khối là những bước đầu tiên cần thiết.