Bối cảnh: Các cộng tác viên của tôi và tôi đang viết một bài báo cho một tạp chí học thuật. Trong quá trình nghiên cứu, chúng tôi đã viết một chương trình mô phỏng bằng Java. Chúng tôi muốn làm cho chương trình mô phỏng có sẵn miễn phí cho người khác sử dụng. Chúng tôi đã quyết định lưu trữ mã trên kho lưu trữ GitHub. Để giúp người khác dễ sử dụng, chúng tôi muốn viết tài liệu tốt cho chương trình của chúng tôi, bao gồm:

• Javadocs cho mỗi lớp và phương thức
• Cách sử dụng mã
• Mô tả cấu trúc cấp cao của mã

Câu hỏi cấp cao của tôi là: Bạn có thể cung cấp một ví dụ hay về các từ và sơ đồ có thể được sử dụng để mô tả cấu trúc cấp cao của một chương trình không? Điều này bao gồm dưới dạng câu hỏi phụ:

1. Làm thế nào để chúng tôi hiển thị các lớp được chứa trong các gói?
2. Làm thế nào để chúng tôi hiển thị các gói phụ thuộc vào các gói khác?
3. Làm thế nào để chúng tôi chỉ ra làm thế nào các đối tượng / lớp trong chương trình làm việc với nhau?
4. Chúng tôi đã cố gắng sử dụng các nguyên tắc thiết kế hướng tên miền trong thiết kế mã của tôi. Làm thế nào để chúng tôi hiển thị sự tương ứng giữa các đối tượng trong miền và các tệp mã nguồn cụ thể mã hóa các đối tượng này? (Xem mô tả "ngôn ngữ phổ biến" của tôi về dự án bên dưới.)

Những gì tôi đã làm cho đến nay

Ngôn ngữ phổ biến

Chúng tôi đặt một mô tả "ngôn ngữ phổ biến" của mã trong một tệp ubiquitous-language.md, nội dung bên dưới.

Mục đích của dự án này là nghiên cứu chính sách bổ sung thực hiện tốt như thế nào trong chuỗi cung ứng đơn giản với một cơ sở duy nhất, theo các mô hình thời gian khác nhau, báo cáo sự chậm trễ và mô hình nhu cầu.

Trong mỗi thời kỳ, các sự kiện sau đây xảy ra:

1. Nếu một lô hàng được lên kế hoạch đến cơ sở ở giai đoạn hiện tại, thì mức tồn kho của cơ sở được tăng lên bởi các đơn vị X.
2. Nếu lịch biểu chỉ ra rằng giai đoạn hiện tại là thời kỳ báo cáo, thì cơ sở sẽ nộp báo cáo cho nhà cung cấp . Nhà cung cấp có thể nhận được báo cáo ngay lập tức hoặc chậm trễ vài tuần, theo quy định của lịch trình .
3. Nếu nhà cung cấp đã nhận được báo cáo , thì dựa trên chính sách bổ sung , họ sẽ tính toán số lượng bổ sung của các đơn vị X. Một lô hàng gồm X đơn vị sản phẩm sẽ được lên lịch để đến sau một khoảng thời gian chính.
4. Khách hàng đến cơ sở và yêu cầu X đơn vị sản phẩm. Bất kỳ nhu cầu chưa được đáp ứng sẽ bị mất.

Cấu trúc mã nguồn

Chúng tôi đặt một mô tả mã "cấp cao" chưa hoàn chỉnh trong một tệp structure.md, nội dung bên dưới.

Cấu trúc cấp gói

Ở cấp độ cao nhất, mã nguồn được tổ chức thành ba gói

• com.gly.sfs Lớp chính với mainphương thức nằm trong gói này.
• com.gly.sfs.model Các lớp mô hình miền nằm trong gói này.
• com.gly.sfs.util Các lớp trợ giúp nằm trong gói này.

Thông thường , bạn sẽ sử dụng UML cho mục đích bạn mô tả. Về cơ bản, UML chia thành hai loại sơ đồ: cấu trúc và hành vi.

Sơ đồ cấu trúc bao gồm: thành phần, triển khai, gói, lớp, đối tượng và thành phần. Sơ đồ hành vi bao gồm: trình tự, máy trạng thái, giao tiếp, trường hợp sử dụng, hoạt động và tổng quan tương tác.

Tùy thuộc vào những gì bạn đang cố gắng truyền đạt, bạn chọn một vài trong số các sơ đồ này thể hiện tốt nhất bất cứ điều gì bạn đang cố gắng truyền đạt và bằng cách đó, bạn cho phép cuộc trò chuyện "tiến lên một cấp độ". Thay vì nói về các phương thức, tham số và mã, bạn đang nói về chuỗi tương tác hoặc phụ thuộc lớp tĩnh hoặc bất kỳ sơ đồ nào bạn chọn để tạo.

Tôi đã đính kèm một ví dụ về sơ đồ trình tự (một trong các sơ đồ hành vi). Cá nhân tôi thích sơ đồ trình tự bởi vì nó ở ngay giữa quy trình tạo tác thiết kế - gần như một số lượng sơ đồ tương đương phụ thuộc vào nó như mong đợi như là đầu vào. Tôi thấy rằng các sơ đồ đầu vào thường được "hiểu" bằng mọi cách, hoặc sơ đồ trình tự đã ngụ ý sự tồn tại của chúng. Tuy nhiên, đôi khi tôi thực hiện cả sơ đồ lớp tĩnh và sơ đồ trình tự (một sơ đồ cấu trúc và một sơ đồ hành vi).

http://omarfrancisco.com/wp-content/uploads/2011/07/fterencediagram.png

Tôi chưa bao giờ thấy sơ đồ này trước đây trong đời, nhưng tôi có thể nói một số điều về hệ thống này. Có bốn thành phần chính (danh từ trong hệ thống của bạn - thường là các lớp): Xem, Trình điều khiển, Proxy dữ liệu và Nhà cung cấp dữ liệu. Các mũi tên là "hành vi" hoặc yêu cầu phương pháp. Một sơ đồ trình tự về cơ bản là tốt để hiển thị một tương tác quan trọng duy nhất giữa một loạt các thành phần. Bạn có một sơ đồ trình tự cho mỗi luồng quan trọng thông qua hệ thống của bạn. Tôi có thể nói từ sơ đồ cụ thể này rằng "Trình điều khiển" hiển thị một phương thức gọi là "phoneIsComplete ()", điều này phụ thuộc vào phương thức "lookupPhone ()" của DataProviderProxy, do đó phụ thuộc vào phương thức "lookupPhone ()" của DataProvider.

Bây giờ, bạn có thể than vãn và nghĩ rằng "uggg ... điều này không cho tôi một bức tranh lớn về hệ thống - đó chỉ là những tương tác riêng lẻ thông qua hệ thống". Tùy thuộc vào độ tinh vi của hệ thống, đó có thể là một mối quan tâm hợp lệ (các hệ thống đơn giản chắc chắn có thể có được chỉ bằng một bộ sưu tập các sơ đồ trình tự). Vì vậy, chúng tôi chuyển sang các sơ đồ cấu trúc và chúng tôi xem xét một cái gì đó giống như sơ đồ lớp tĩnh:

http://www.f5systems.in/apnashoppe/education//img/ch chương / uml_group_diagram.jpg

Biểu đồ lớp giúp chúng ta tìm ra hai điều quan trọng: cardinality và các loại mối quan hệ lớp. Các lớp có thể liên quan với nhau theo những cách khác nhau: liên kết, tổng hợp và thành phần. Về mặt kỹ thuật, có một sự khác biệt giữa "mối quan hệ lớp tĩnh" và "mối quan hệ cá thể". Tuy nhiên, trong thực tế bạn thấy những dòng này bị mờ. Sự khác biệt chính là các mối quan hệ lớp tĩnh thường không bao gồm cardinality. Hãy xem ví dụ trên và xem những gì chúng ta có thể thấy. Đầu tiên, chúng ta có thể thấy rằng "Đơn hàng đặc biệt" và "Đơn hàng bình thường" là các kiểu con của "Đơn hàng" (thừa kế). Chúng ta cũng có thể thấy rằng một Khách hàng có N Đơn hàng (có thể là "Đơn hàng bình thường", "Đơn hàng" hoặc "Đơn hàng đặc biệt") - đối tượng Khách hàng không ' t thực sự biết Chúng ta cũng có thể thấy một số phương thức (ở nửa dưới của mỗi hộp lớp) và các thuộc tính (nửa trên của mỗi hộp lớp).

Tôi có thể tiếp tục nói về các sơ đồ UML trong một thời gian dài, nhưng đây là điều cơ bản. Hy vọng rằng sẽ giúp.

TLDR; Chọn một sơ đồ UML hành vi và một cấu trúc, tìm hiểu cách tạo nó và bạn sẽ hoàn thành những gì bạn đang cố gắng thực hiện.

Nếu bạn gặp khó khăn khi mô tả những thứ như cách cấu trúc cấp cao của chương trình của bạn hoạt động và cách các lớp hoạt động tốt với nhau, hãy xem xét câu châm ngôn sau:

A picture is worth a thousand words.

Cách bạn vẽ một bức tranh về mã là cung cấp các ví dụ về mã. Rất nhiều trong số họ. Đây là cách bạn tạo một khách hàng mới (mã). Đây là cách bạn xử lý một đơn đặt hàng (mã). Điều này không chỉ cung cấp cho người tiêu dùng mã của bạn một nơi để bắt đầu, nó còn minh họa cách tất cả các đối tượng kết nối với nhau và tương tác. Nếu tôi đang sử dụng mã của bạn, ưu tiên lớn nhất bạn có thể làm là cung cấp nhiều mẫu mã.

Cách bạn vẽ một bức tranh cho người dùng cuối là cung cấp ảnh chụp màn hình. Rất nhiều trong số họ. Ảnh chụp màn hình sau ảnh chụp màn hình minh họa, nếu bạn muốn thực hiện tác vụ này, đây là việc bạn làm trước, đây là việc bạn làm tiếp theo, v.v.

UML, trong khi thường được sử dụng để mô hình hóa phần mềm trước khi nó được tạo ra, có thể hữu ích. Có một số sơ đồ khác nhau minh họa các trường hợp sử dụng, tương tác lớp, v.v. Bạn có thể xem thêm về nó ở đây .

Tôi tìm thấy https://www.web resultencediagrams.com/ một công cụ cực kỳ hữu ích để mô tả sự tương tác giữa các thành phần trong một ứng dụng hoặc giữa các dịch vụ trong một ứng dụng phân tán. Nó chỉ làm cho quá trình tạo và duy trì sơ đồ trình tự UML dễ dàng hơn nhiều.

Điều tuyệt vời là, nếu bạn coi mỗi huyết mạch là giao diện hoặc lớp trong ứng dụng của mình (tôi thường chỉ mô hình hóa các trình phát lớn), thì mỗi dòng chảy vào lớp đó đại diện cho một phương thức mà bạn phải hỗ trợ.

Ngoài ra, có một số tùy chọn tải xuống để có được hình ảnh. Cũng có một số cách dễ dàng để nhúng sơ đồ vào wiki. Vì vậy, đây là một công cụ giao tiếp tuyệt vời để mô tả sự tương tác giữa các thành phần hoặc dịch vụ trong một hệ thống, cũng như giao tiếp với nhóm.