Tôi đã tham gia vào giữa một dự án cỡ trung bình, đã hoạt động được vài năm. Một trong những vấn đề là tài liệu mô tả kiến ​​trúc không bao giờ được viết. Bây giờ tôi được giao một nhiệm vụ để viết mô tả kiến ​​trúc.

Trong thời gian tôi làm việc trong dự án này, tôi đã thu thập tất cả thông tin tôi cần để viết tài liệu. Vì tôi cũng đã thêm một số tính năng, tôi đã xác định một số đoạn mã rõ ràng đang phá vỡ kiến ​​trúc như được mô tả.

Ví dụ, GUI được cho là một lớp mỏng, không có logic nghiệp vụ. Đó là những gì tôi đã nói. Việc thực hiện chứa rất nhiều logic.

Ông chủ của tôi giao cho tôi nhiệm vụ, để viết tài liệu mô tả kiến ​​trúc của hệ thống. Đối tượng mục tiêu là các nhà phát triển hiện tại và tương lai làm việc trong dự án. Tôi cần mô tả những gì nên được, nhưng tôi cũng cần mô tả những sai lệch bằng cách nào đó.

Vì vậy, tôi nên mô tả những vấn đề này ở đâu? Lỗi theo dõi phần mềm? Hay tôi nên mô tả những sai lệch của việc thực hiện so với kiến ​​trúc trong tài liệu mô tả kiến ​​trúc của hệ thống?

Nếu bạn đang tạo tài liệu cho một thiết kế hoặc kiến ​​trúc của một hệ thống đã được xây dựng, tài liệu sẽ mô tả nó như được xây dựng và không được thiết kế hoặc theo dự định. Nếu có những điểm kỳ lạ hoặc khác biệt trong kiến ​​trúc, thì tài liệu này nên gọi ra những vấn đề đó và giải thích chúng càng nhiều càng tốt cho người đọc.

Nếu bạn có thể nhận thông tin từ những người đã làm việc trên hệ thống ngay từ đầu (hoặc ít nhất là lâu hơn bạn có), sẽ rất hữu ích khi nắm bắt thêm thông tin về những gì thực sự được dự định và tại sao kiến ​​trúc và thiết kế lệch khỏi điều này ý định.

Vào cuối ngày, một tài liệu thiết kế sẽ phục vụ như một hướng dẫn về mã. Nếu tài liệu không giúp nhà phát triển mới hiểu trạng thái hiện tại của cơ sở mã và cách cấu trúc, thì tài liệu không hữu ích.

Tài liệu này phải là một tài liệu sống được sử dụng để hướng dẫn lập kế hoạch và thiết kế các thay đổi trong tương lai cho hệ thống và sau đó được cập nhật tương ứng, trong quá trình phát triển của bạn. Khi thiết kế thay đổi và phát triển theo thời gian, tài liệu cũng sẽ giúp các nhà phát triển hiểu tại sao mọi thứ lại diễn ra như hiện tại.

Nếu bạn đang tìm kiếm lời khuyên về việc nắm bắt kiến ​​trúc, tôi thích cách tiếp cận được ủng hộ trong Tiêu chuẩn IEEE 1016-2009 Tiêu chuẩn IEEE về Công nghệ thông tin - Thiết kế hệ thống - Mô tả thiết kế phần mềm . Nó cung cấp một cấu trúc hợp lý cho một mô tả thiết kế, có thể được sử dụng để nắm bắt cả thông tin thiết kế cấp độ kiến ​​trúc và chi tiết.

Tôi cũng sẽ coi những sai lệch này là một dạng nợ kỹ thuật. Nó có thể là một công việc lớn, thậm chí có thể là một dự án nhỏ, để khắc phục các vấn đề, tôi khuyên bạn nên làm cho sự tồn tại của các khoản nợ kỹ thuật rõ ràng hơn. Nếu điều đó có nghĩa là bạn sử dụng công cụ theo dõi lỗi của mình, thì bạn có thể đặt một hoặc nhiều vấn đề ở đó. Nếu bạn có một công cụ khác mà bạn sử dụng để theo dõi các đề xuất và cải tiến cho phần mềm, đó có thể là một nơi khác để đặt nó.

Khi chính thức hóa kiến ​​trúc của hệ thống, điều quan trọng là bạn hiểu không chỉ giá trị đằng sau những gì kiến ​​trúc sẽ mang lại cho bảng, mà còn để hiểu và đánh giá cao những gì nó nên được.

Mục tiêu chính của Kiến trúc phần mềm hoặc Kỹ thuật là xác định các yêu cầu phi chức năng được thực hiện bởi các thuộc tính chất lượng sẽ thúc đẩy Kiến trúc hệ thống .

Về các yêu cầu phi chức năng:

Yêu cầu phi chức năng là một yêu cầu chỉ định các tiêu chí có thể được sử dụng để đánh giá hoạt động của một hệ thống, thay vì các hành vi cụ thể. Chúng tương phản với các yêu cầu chức năng xác định hành vi hoặc chức năng cụ thể. Kế hoạch thực hiện các yêu cầu chức năng được chi tiết trong thiết kế hệ thống. Kế hoạch thực hiện các yêu cầu phi chức năng được trình bày chi tiết trong kiến ​​trúc hệ thống.

Nói chung, các yêu cầu chức năng xác định những gì một hệ thống được cho là phải làm và các yêu cầu phi chức năng xác định cách thức một hệ thống được coi là. ... Các yêu cầu phi chức năng thường được gọi là "thuộc tính chất lượng" của một hệ thống. Các thuật ngữ khác cho các yêu cầu phi chức năng là "phẩm chất", "mục tiêu chất lượng", "chất lượng yêu cầu dịch vụ", "ràng buộc" và "yêu cầu phi hành vi"

Tất nhiên, việc xác định các yêu cầu có ý nghĩa về mặt kiến ​​trúc có ý nghĩa khi trên một dự án trường xanh, tuy nhiên khi làm việc với phần mềm hiện có, tốt nhất là nên xử lý kỷ luật nhất có thể. Bạn sẽ không muốn kiến ​​trúc phần mềm của mình bị ảnh hưởng bởi hệ thống hiện có.

Kiến trúc phần mềm để có thẩm quyền thực sự cần phải có 3 điều.

Tuyên bố

Đây là một phần của tài liệu mà bạn tuyên bố KHÔNG PHẢI LÀ GÌ, nhưng làm thế nào mọi thứ NÊN. Chúng tôi làm điều này thông qua việc sử dụng các Quan điểm kiến ​​trúc khác nhau của hệ thống. Chúng tôi xác định các thành phần nên, cách chúng tương tác và sau đó chúng tôi tùy ý đi sâu vào từng thành phần để có chế độ xem chi tiết hơn tuyên bố cách thiết kế hệ thống.

Đây là một dấu hiệu đặc biệt quan trọng. Thiết kế hệ thống nên bị ràng buộc bởi Kiến trúc hệ thống, trên thực tế chúng là những thứ riêng biệt nhưng có liên quan.

Cơ sở lý luận

Cơ sở lý luận của Kiến trúc phần mềm của bạn là những gì cung cấp tính hợp pháp và quyền hạn cho các quyết định kiến ​​trúc đã được đưa ra. Có lẽ quyết định đã được đưa ra để sử dụng một người nghe sự kiện Pub / Sub qua MQ để kích hoạt một công việc hàng loạt và bạn lập sơ đồ đó?

Tại sao quyết định này được đưa ra? Chúng tôi giải thích lý do tại sao trong phần Đặt vấn đề và liên kết lại phần giải thích của chúng tôi với Yêu cầu phi chức năng, Mục tiêu thuộc tính chất lượng hoặc Yêu cầu quan trọng về mặt kiến ​​trúc. (Vd ..)

Rủi ro

Bây giờ bạn đã tuyên bố kiến ​​trúc nên như thế nào và chứng minh nó với Cơ sở lý luận của bạn, bây giờ bạn có thể xác định Rủi ro về trạng thái hiện tại của hệ thống để điều này không tuân thủ.

(Ví dụ: Xác thực phía máy chủ đang được sao chép trên mã Javascript phía máy khách. Điều này vi phạm nguyên tắc DRY và điều này chạy ngược lại Thuộc tính chất lượng của khả năng bảo trì. Không có yêu cầu phi chức năng nào được xác định xung quanh Hiệu suất trong khu vực này vì vậy không có không có lý do cho hành vi hệ thống hiện tại)

Rủi ro của bạn cũng có thể lập sơ đồ nơi trạng thái hiện tại đang đi chệch khỏi Kiến trúc. Những rủi ro này có thể được giải quyết bởi nhóm phát triển, thông qua kế hoạch dự án của họ hoặc bằng cách thêm điều này vào hồ sơ tồn đọng.

Bạn thực sự cần phải quyết định xem bạn có nên ghi lại cấu trúc hiện tại của dự án hay cấu trúc mong muốn của dự án hay cả hai.

Bạn có thể ghi lại mục tiêu, với mục đích hướng dẫn sự phát triển trong tương lai dọc theo các dòng mong muốn và nâng cao độ lệch là lỗi (có thể liên kết đến các lỗi này từ các phần có liên quan của tài liệu). Hoặc bạn có thể ghi lại thực tế để cung cấp phần giới thiệu / tổng quan về mã. Hoặc bạn có thể viết tài liệu song song, để bạn đồng thời có một hướng dẫn cho sự phát triển trong tương lai và mô tả chính xác về mã hiện tại ở một nơi. Tất cả đều hợp lý tùy thuộc vào những gì tài liệu được cho là dành cho, vì vậy tôi không nghĩ rằng chúng tôi có thể hữu ích cho bạn biết nên làm gì.

Bạn cũng nên nhớ rằng kiến trúc mong muốn có thể không được thống nhất giữa những người liên quan (vì họ muốn những thứ khác nhau, hoặc vì một số trong số họ đã nhận ra rằng một số mong muốn chia sẻ ban đầu là không thể hoặc không thực tế và do đó phải dùng đến việc viết mã hiện có mà đi lệch khỏi mục tiêu). Vì vậy, bạn cũng cần biết liệu bạn có quyền quyết định những gì mong muốn hay không và nếu không thì ai làm. Cấu trúc hiện có ít nhất có một ưu điểm là chỉ có một trong số đó để làm tài liệu!

Viết vào tài liệu thiết kế kiến ​​trúc những gì được cho là và đối với mỗi xung đột, bạn tìm thấy mở một vé trong trình theo dõi lỗi mô tả xung đột. Phần bình luận của vé sẽ cung cấp một nền tảng cho những người có liên quan để thảo luận về xung đột cụ thể đó.

Lưu ý rằng độ phân giải của mỗi vé này có thể thay đổi việc triển khai để phù hợp với thiết kế - nhưng cũng có thể thay đổi thiết kế để phù hợp với việc thực hiện. Lý tưởng nhất là trước đây được ưa thích, nhưng đôi khi có những hạn chế về kỹ thuật và / hoặc kinh doanh làm cho nó hiệu quả hơn / thực dụng / có thể chọn sau này. Trong trường hợp đó, có thể là một ý tưởng tốt để tham khảo vé từ tài liệu thiết kế kiến ​​trúc, để những độc giả tương lai không hiểu tại sao lựa chọn thiết kế kém đặc biệt đó được chọn có thể đọc thảo luận trong vé và hiểu lý do đằng sau nó

Tôi sẽ có xu hướng viết một tài liệu kiến ​​trúc được tổ chức thành 3 phần chính.

Việc đầu tiên giới thiệu thiết kế / kiến ​​trúc đã được dự định ban đầu. Điều này sẽ cho phép các nhà phát triển / độc giả mới có được ý tưởng về những gì hệ thống phải làm và rõ ràng nên được gắn với các yêu cầu / usecase, v.v.

Phần thứ hai sẽ giải thích rất rõ ràng chính xác kiến ​​trúc thực sự là gì. Điều này cho phép các nhà phát triển / độc giả mới có được ý tưởng về trạng thái chơi hiện tại và những gì họ đang giải quyết nếu họ xem phần mềm (và có khả năng là tài liệu khác). Phần này sẽ chỉ ra rõ ràng sự khác biệt giữa những gì đã được dự định và thực tế vì điều này rất có thể sẽ làm sáng tỏ những điều rất sai với kiến ​​trúc ban đầu (hy vọng không quá nhiều!) Và các khu vực nơi các phím tắt / hack (có thể là một số ít nếu có một mức độ áp lực lớn đối với nhóm nhà phát triển) đã được đưa ra và các yêu cầu không được đáp ứng hoặc phần mềm đang cầu xin để trông "kém" được thiết kế tức là mỏng manh, không ổn định, không thể mang theo được.

Cuối cùng tôi nghĩ rằng một phần chi tiết các khuyến nghị cho những gì cần phải xảy ra bây giờ. Đây phải là bất kỳ thay đổi nào đối với kiến ​​trúc / thiết kế và lộ trình thay đổi phần mềm hiện tại để biến tầm nhìn của bạn trở thành hiện thực.

Tôi nghĩ cái này bao gồm (ở cấp độ cao) những gì cần phải nắm bắt. Cách bạn thực hiện việc này theo các phần phụ của tài liệu hoặc phần mềm theo dõi lỗi bạn sử dụng thuộc về miền bạn đang làm việc / sở thích cá nhân / quy mô nhóm / ngân sách / quy mô thời gian, v.v.