Cách làm cho một cơ sở mã lớn dễ hiểu hơn

Giả sử rằng tôi đang phát triển một dự án tương đối lớn. Tôi đã ghi lại tất cả các lớp và chức năng của mình với Doxygen, tuy nhiên, tôi có ý tưởng đặt "ghi chú của lập trình viên" vào mỗi tệp mã nguồn.

Ý tưởng đằng sau điều này là để giải thích theo thuật ngữ của giáo dân về cách một lớp cụ thể hoạt động (và không chỉ tại sao như hầu hết các bình luận làm). Nói cách khác, để cung cấp cho các lập trình viên đồng nghiệp một cái nhìn khác về cách một lớp hoạt động.

Ví dụ:

/*
 * PROGRAMMER'S NOTES:
 *
 * As stated in the documentation, the GamepadManager class 
 * reads joystick joystick input using SDL and 'parses' SDL events to
 * Qt signals.
 *
 * Most of the code here is about goofing around the joystick mappings.
 * We want to avoid having different joystick behaviours between
 * operating systems to have a more integrated user experience, since
 * we don't want team members to have a bad surprise while
 * driving their robots with different laptops.
 *
 * Unfortunately, we cannot use SDL's GamepadAPI because the robots
 * are interested in getting the button/axes numbers, not the "A" or
 * "X" button.
 *
 * To get around this issue, we created a INI file for the most common 
 * controllers that maps each joystick button/axis to the "standard" 
 * buttons and axes used by most teams. 
 *
 * We choose to use INI files because we can safely use QSettings
 * to read its values and we don't have to worry about having to use
 * third-party tools to read other formats.
 */

Đây có phải là một cách tốt để làm cho một dự án lớn dễ dàng hơn cho các lập trình viên / cộng tác viên mới hiểu cách thức hoạt động của nó? Ngoài việc duy trì một phong cách mã hóa nhất quán và tổ chức thư mục 'tiêu chuẩn', còn có 'tiêu chuẩn' hay khuyến nghị nào cho những trường hợp này không?

Điều này thật tuyệt. Tôi muốn nhiều nhà phát triển phần mềm đã dành thời gian và nỗ lực để làm điều này. Nó:

• Nói bằng tiếng Anh đơn giản những gì lớp học làm (nghĩa là trách nhiệm),
• Cung cấp thông tin bổ sung hữu ích về mã mà không lặp lại nguyên văn những gì mã đã nói,
• Phác thảo một số quyết định thiết kế và lý do tại sao chúng được đưa ra, và
• Làm nổi bật một số vấn đề có thể xảy ra với người tiếp theo đọc mã của bạn.

Than ôi, nhiều lập trình viên rơi vào trại "nếu mã được viết đúng, nó không cần phải được ghi lại." Không đúng. Có nhiều mối quan hệ hàm ý giữa các lớp mã, phương thức, mô-đun và các tạo phẩm khác không rõ ràng từ việc chỉ đọc chính mã.

Một lập trình viên có kinh nghiệm có thể cẩn thận chế tạo một thiết kế có kiến ​​trúc rõ ràng, dễ hiểu, rõ ràng mà không cần tài liệu. Nhưng có bao nhiêu chương trình như thế bạn đã thực sự thấy?

Chìa khóa để làm việc với một cơ sở mã lớn là không phải đọc toàn bộ cơ sở mã để thực hiện thay đổi. Để cho phép một lập trình viên nhanh chóng tìm thấy mã mà anh ta đang tìm kiếm, mã phải được tổ chức và tổ chức rõ ràng. Nghĩa là, mỗi đơn vị logic trong mã, từ tệp thực thi, thư viện, không gian tên, đến lớp riêng lẻ phải có trách nhiệm rõ ràng rõ ràng. Do đó, tôi sẽ không chỉ tài liệu các tập tin nguồn, mà còn các thư mục họ cư trú.

Ghi chú của lập trình viên của bạn cũng đưa ra nền tảng về các quyết định thiết kế. Mặc dù đây có thể là thông tin có giá trị, tôi sẽ tách nó ra khỏi tuyên bố trách nhiệm (để cho phép người đọc chọn xem anh ta có muốn đọc về trách nhiệm của lớp học hay lý do thiết kế của nó không) và di chuyển nó gần với nguồn mà nó mô tả càng tốt, để tối đa hóa cơ hội tài liệu được cập nhật khi mã được (tài liệu chỉ hữu ích nếu chúng ta có thể tin tưởng vào độ chính xác của nó - tài liệu lỗi thời có thể tệ hơn không có gì!).

Điều đó nói rằng, tài liệu nên vẫn là DRY, tức là không lặp lại thông tin có thể được thể hiện bằng mã hoặc đã được mô tả ở nơi khác (cụm từ như "như các trạng thái tài liệu" là một dấu hiệu cảnh báo). Cụ thể, những người duy trì trong tương lai sẽ chỉ thành thạo ngôn ngữ lập trình của dự án như bằng tiếng Anh; diễn giải việc thực hiện trong các bình luận (mà tôi thấy hoàn toàn quá thường xuyên khi mọi người tự hào về tài liệu của họ) không có lợi ích gì, và có khả năng chuyển hướng khỏi việc thực hiện, đặc biệt nếu tài liệu không ở gần mã mà nó mô tả.

Cuối cùng, cấu trúc của tài liệu nên được chuẩn hóa trong toàn dự án để mọi người có thể tìm thấy nó (đó là một mớ hỗn độn của các tài liệu Peter trong trình theo dõi lỗi, Sue trong wiki, Alan trong readme và John trong mã nguồn ...) .

Tôi không đồng ý đây là một cách tiếp cận rất tốt, chủ yếu là do

1. Khi bạn cấu trúc lại dự án của mình, di chuyển các phương thức xung quanh, tài liệu sẽ bị hỏng.

2. Nếu tài liệu không được cập nhật đúng cách, nó sẽ dẫn đến sự nhầm lẫn nhiều hơn là giúp hiểu mã.

Nếu bạn có các bài kiểm tra đơn vị cho từng phương pháp / kiểm tra tích hợp cho từng mô-đun, thì đó sẽ là một tài liệu tự bảo trì dễ hiểu và dễ hiểu hơn so với nhận xét mã.

Vâng, có một cấu trúc thư mục thích hợp chắc chắn sẽ giúp.

Cá nhân tôi là một fan hâm mộ của một tài liệu thiết kế cấp cao - tốt nhất là được viết TRƯỚC bất kỳ mã nào - đưa ra một cái nhìn tổng quan về thiết kế và một danh sách các lớp và tài nguyên. Thiết kế từ trên xuống đơn giản hóa rất nhiều thứ - của bạn có thể là "công cụ trò chơi -> phần cứng -> bộ điều khiển -> cần điều khiển"; do đó, một lập trình viên mới nói "sửa nút 'a' trên bộ điều khiển 'xyz" ít nhất sẽ biết bắt đầu tìm ở đâu.

Quá nhiều ngôn ngữ hiện đại có xu hướng phá mã thành hàng trăm tệp nhỏ, vì vậy chỉ cần tìm đúng tệp có thể là một thách thức đối với ngay cả một dự án vừa phải.

Nếu cơ sở mã lớn - tôi cố gắng cung cấp một tài liệu thiết kế để vạch ra các yếu tố chính của thiết kế và việc thực hiện . Ý định ở đây không phải là chi tiết bất kỳ lớp nào được sử dụng, mà cung cấp một khóa để viết mã và ý nghĩ đi vào thiết kế. Nó đưa ra một bối cảnh bao quát cho hệ thống, các thành phần của nó và ứng dụng của nó.

Những điều cần bao gồm trong tài liệu thiết kế là;

• Kiến trúc ứng dụng
• Cấu trúc mã logic
• Luồng dữ liệu
• Các mẫu chính được sử dụng và động lực đằng sau việc sử dụng chúng
• Cấu trúc nguồn mã
• Cách xây dựng nó (điều này cung cấp cái nhìn sâu sắc về các phụ thuộc ngầm định và cấu trúc nguồn mã vật lý)

Theo đó, tài liệu cho các lớp và các hàm / phương thức nên được hoàn thành khi thích hợp . Cụ thể là API công khai; cần phải rõ ràng tất cả những gì sau đây trong mỗi trường hợp;

• Điều kiện tiên quyết
• Các hiệu ứng
• Bất biến
• Điều kiện ngoại lệ (ném)

Quy tắc quan trọng nhất mà tôi đã tìm thấy để giúp các nhà phát triển mới dễ dàng hiểu được một cơ sở mã là thỏa thuận hoàn hảo là tốn kém.

Nếu các nhà phát triển mới phải hiểu một cách hoàn hảo hệ thống mà họ đang làm việc, nó sẽ ngăn chặn tất cả các cơ hội cho việc học. Tôi nghĩ rằng các ghi chú của lập trình viên là một khởi đầu tuyệt vời, nhưng tôi sẽ đi xa hơn. Cố gắng viết mã, nếu được tiếp cận một lần nữa, sẽ cho phép nhà phát triển tìm ra những gì họ đang làm một cách nhanh chóng, thay vì yêu cầu họ tìm hiểu trước khi họ làm. Những điều nhỏ nhặt như khẳng định cho các trường hợp bạn biết không bao giờ có thể xảy ra, cùng với các bình luận giải thích lý do tại sao khẳng định đó là hợp lệ, đi một chặng đường dài. Viết mã không thành công một cách duyên dáng thay vì viết sai nếu bạn làm bất cứ điều gì sai.

Tôi đã thấy các lớp lớn có tài liệu và sau khi đọc tài liệu tôi không biết được lớp này được cho là tốt và tại sao mọi người sẽ sử dụng nó! Đồng thời, tôi có nhu cầu về một số chức năng và tôi hoàn toàn chắc chắn rằng phải có một lớp để xử lý nó và không thể tìm thấy nó ở bất cứ đâu - bởi vì không có tài liệu nào đưa tôi từ những gì tôi cần đến lớp làm việc đó.

Vì vậy, điều đầu tiên mà tôi muốn trong tài liệu chỉ là một vài câu mà một lớp học làm gì và tại sao tôi lại muốn sử dụng nó. Các ý kiến ​​trong câu hỏi ban đầu đang làm khá tốt trong khía cạnh đó. Sau khi đọc những bình luận này, nếu tôi có một phím điều khiển không hoạt động tốt bởi vì tôi không thể diễn giải các giá trị mà nó mang lại, tôi sẽ biết nên kiểm tra mã nào.

Tương tự như những gì @meriton đã nói, hãy chia mã thành các thành phần riêng biệt. Thậm chí tốt hơn, chia cơ sở mã thành các gói riêng biệt (JAR, đá quý, trứng, bất cứ thứ gì) để làm cho nó rõ ràng hơn về cách các thành phần được tách ra. Nếu có lỗi, nhà phát triển chỉ cần tìm gói có lỗi và (hy vọng) chỉ sửa nó ở đó. Chưa kể, việc kiểm tra đơn vị sẽ dễ dàng hơn và bạn có thể tận dụng lợi thế của quản lý phụ thuộc.

Một giải pháp khác: làm cho codebase nhỏ hơn. Càng ít mã, càng dễ hiểu. Tái cấu trúc ra mã không sử dụng hoặc trùng lặp. Sử dụng các kỹ thuật lập trình khai báo . Điều này đòi hỏi nỗ lực, tất nhiên, và thường là không thể hoặc thực tế. Nhưng đó là một mục tiêu xứng đáng. Như Jeff Atwood đã viết: Mã tốt nhất là không có mã nào cả

Đối với các hệ thống phức tạp, có thể đáng để không chỉ ghi lại từng tệp, mà cả các tương tác và phân cấp của chúng, và cách cấu trúc chương trình và lý do.

Ví dụ, một công cụ trò chơi thường khá phức tạp và thật khó để quyết định cái gì gọi là gì sau hàng trăm lớp trừu tượng. Có thể đáng để tạo một tệp như "Architecture.txt" để giải thích cách thức và lý do tại sao mã được cấu trúc như thế này và tại sao lại có lớp trừu tượng trông vô nghĩa ở đó.

Điều này có thể là một phần bởi vì rất khó để một lập trình viên viết nó, vì mỗi cá nhân chỉ hiểu một phần dự án của họ.

Đôi khi bạn có thể lấy thông tin này từ các ghi chú của người quản lý dự án, nhưng đó là tất cả những gì bạn sẽ nhận được, vì họ sẽ hiếm khi viết lại ghi chú của họ ở định dạng này.