나는 이미 몇 년 동안 진행된 중간 규모 프로젝트 중간에 합류했습니다. 문제 중 하나는 아키텍처를 설명하는 문서가 작성되지 않았다는 것입니다. 이제 아키텍처 설명을 작성하는 작업이 할당되었습니다.

이 프로젝트를 진행하는 동안 문서 작성에 필요한 모든 정보를 수집했습니다. 몇 가지 기능도 추가 했으므로 코드 조각을 식별하여 설명 된대로 아키텍처를 명확히 깨뜨 렸습니다.

예를 들어, GUI는 비즈니스 로직이없는 얇은 계층이어야합니다. 그것이 내가 들었던 것입니다. 구현에는 많은 논리가 포함됩니다.

상사는 시스템 아키텍처를 설명하는 문서를 작성하는 작업을 내게 할당했습니다. 대상 독자는 프로젝트에서 작업하는 현재 및 미래 개발자입니다. 무엇이되어야하는지 설명해야하지만 어쨌든 편차도 설명해야합니다.

그렇다면이 문제들을 어디에 설명해야합니까? 버그 추적 소프트웨어? 아니면 시스템 아키텍처를 설명하는 문서에서 아키텍처와 구현의 편차를 설명해야합니까?

이미 구축 된 시스템의 설계 또는 아키텍처를 문서화하는 경우 문서는 설계 또는 의도 한대로 구축되지 않은 상태로 설명해야합니다. 아키텍처에 이상이나 불일치가있는 경우이 문서는 이러한 문제를 불러내 독자에게 가능한 많이 설명해야합니다.

처음부터 시스템을 작업 한 사람들로부터 정보를 얻을 수 있다면 (또는 적어도 자신보다 오래), 실제로 의도 한 것과 아키텍처와 디자인이 왜 벗어난 지에 대한 더 많은 정보를 캡처하는 것이 유용 할 것입니다 의향.

하루가 끝나면 디자인 문서가 코드 가이드 역할을해야합니다. 문서가 새로운 개발자가 코드베이스의 현재 상태와 구조를 이해하는 데 도움이되지 않으면 문서보다 유용하지 않습니다.

이 문서는 향후 시스템 변경 계획 및 설계를 안내하고 개발 프로세스 내에서 적절하게 업데이트하는 데 사용되는 실제 문서 여야합니다. 시간이 지남에 따라 디자인이 변경되고 발전함에 따라 개발자는 문서가 현재의 방식을 이해하는 데 도움이됩니다.

아키텍처 캡처에 대한 조언을 찾고 있다면 IEEE 표준 1016-2009 IEEE 표준 정보 기술-시스템 설계-소프트웨어 디자인 설명 에서 주장하는 접근 방식이 마음에 듭니다 . 이는 설계 설명을위한 합리적인 구조를 제공하며, 이는 건축 및 상세 수준 설계 정보를 모두 캡처하는 데 사용될 수 있습니다.

또한 이러한 편차를 기술 부채의 한 형태로 간주합니다. 문제를 해결하는 것은 큰 사업 일 수도 있고 작은 프로젝트 일 수도 있습니다. 기술 부채의 존재를보다 잘 보이게 만드는 것이 좋습니다. 이것이 결함 추적 도구를 사용한다는 것을 의미하는 경우 하나 이상의 문제를 둘 수 있습니다. 소프트웨어에 대한 제안 및 개선 사항을 추적하는 데 사용하는 다른 도구가있는 경우 다른 도구로 사용할 수 있습니다.

시스템 아키텍처를 공식화 할 때 아키텍처가 테이블에 가져 오는 것의 가치를 이해해야 할뿐만 아니라 그 구조가 무엇인지 이해하고 이해하는 것이 중요합니다.

소프트웨어 또는 기술 아키텍처의 기본 목표 는 시스템 아키텍처를 주도 할 품질 속성에 의해 실현되는 기능 외 요구 사항 을 식별 하는 것 입니다.

비 기능 요구 사항 :

비 기능적 요구 사항은 특정 동작이 아닌 시스템 작동을 판단하는 데 사용할 수있는 기준을 지정하는 요구 사항입니다. 특정 동작이나 기능을 정의하는 기능 요구 사항과 대조됩니다. 기능 요구 사항 구현 계획은 시스템 설계에 자세히 설명되어 있습니다. 비 기능적 요구 사항을 구현하기위한 계획은 시스템 아키텍처에 자세히 설명되어 있습니다.

기능 요구 사항은 일반적으로 시스템의 기능을 정의하고 비 기능 요구 사항은 시스템의 동작 방식을 정의합니다. 비 기능적 요구 사항은 종종 시스템의 "품질 속성"이라고합니다. 기능 외 요구 사항에 대한 다른 용어는 "품질", "품질 목표", "서비스 품질 요구 사항", "제약 사항"및 "비 동작 요구 사항"입니다.

물론 그린 필드 프로젝트에서는 건축 적으로 중요한 요구 사항을 식별하는 것이 합리적이지만 기존 소프트웨어로 작업 할 때는 가능한 한 훈련을받는 것이 가장 좋습니다. 소프트웨어 아키텍처가 기존 시스템의 영향을받지 않기를 바랍니다.

권위있는 소프트웨어 아키텍처는 실제로 3 가지가 필요합니다.

선언적

이것은 당신이 무엇을 선언하지 않는지 문서의 일부이지만 어떻게해야 하는지를 알려줍니다. 우리는 시스템의 다양한 아키텍처 뷰를 사용하여이를 수행합니다. 구성 요소와 구성 요소의 상호 작용 방식을 정의한 다음 선택적으로 시스템을 설계해야하는 방식을 나타내는보다 세부적인보기를 위해 각 구성 요소를 드릴 다운합니다.

이것은 중요한 차이점입니다. 시스템 설계는 시스템 아키텍처에 의해 제약을 받아야하며, 실제로는 별개이지만 관련이 있습니다.

이론적 해석

소프트웨어 아키텍처의 이론적 근거는 아키텍처 결정에 대한 합법성과 권한을 제공하는 것입니다. 배치 작업을 트리거하기 위해 MQ를 통해 Pub / Sub 이벤트 리스너를 사용하기로 결정한 후 다이어그램을 작성 했습니까?

이 결정이 내려진 이유는 무엇입니까? 이론적 근거 섹션에서 이유를 설명하고 기능 요구 사항, 품질 속성 목표 또는 구조적으로 중요한 요구 사항에 대한 설명을 다시 연결합니다. (예 : 작업은 비동기식이고 반복 가능해야합니다. 품질 속성으로서 유지 보수성은 배치 작업 실패시 작업이 MQ 메시지를 통해 다시 시작될 수 있도록하고, 시스템은 비동기 통신으로 메시지 손실이 없어야합니다. ..)

위험

이제 이론을 근거로 아키텍처를 구현하고 증명하는 방법을 선언 했으므로 이제 시스템의 현재 상태에서이를 준수하지 않는 위험을 식별 할 수 있습니다.

(예 : 서버 측 유효성 검사는 클라이언트 측 Javascript 코드에서 복제되고 있습니다. 이는 DRY 원칙을 위반하는 것으로 유지 관리의 품질 속성과 상반됩니다.이 영역의 성능과 관련하여 정의 된 비 기능적 요구 사항이 없으므로 현재 시스템 동작에 대한 근거가 없음)

리스크는 현재 상태가 현재 아키텍처에서 벗어난 위치를 다이어그램으로 표시 할 수도 있습니다. 이러한 위험은 프로젝트 계획을 통해 또는 백 로그에 추가하여 개발 팀이 해결할 수 있습니다.

프로젝트 의 현재 구조 또는 원하는 프로젝트 구조 또는 둘 다를 문서화해야하는지 여부를 실제로 결정해야 합니다.

원하는 라인을 따라 향후 개발을 안내하기 위해 목표를 문서화하고 편차를 버그로 제기 할 수 있습니다 (문서의 관련 부분에서 이러한 버그로 연결될 수 있음). 또는 코드에 대한 소개 / 개요를 제공하기 위해 현실을 문서화 할 수 있습니다. 또는 나란히 나란히 문서화하여 향후 개발을위한 가이드 와 현재 코드에 대한 정확한 설명을 한 곳에 동시에 제공 할 수 있습니다 . 문서의 용도에 따라 모두 합리적이므로 어떤 문서를 작성해야하는지 유용하게 판단 할 수 없습니다.

또한 원하는 아키텍처가 다른 것들을 원하거나 일부 공유 욕구가 불가능하거나 비현실적이며 기존 코드 작성에 의존한다는 사실을 알고 있기 때문에 관련 아키텍처 사이에서 보편적으로 합의되지 않을 수도 있음을 명심해야합니다. 목표에서 벗어난 것). 따라서 원하는 것을 결정할 권한이 있는지 여부 와 누가 그렇지 않은지 를 결정 해야합니다. 기존 구조는 적어도 하나만 문서화해야한다는 장점이 있습니다!

아키텍처 디자인 문서에 작성해야 할 내용을 작성하고 각 충돌에 대해 충돌을 설명하는 버그 추적기에서 티켓을 엽니 다. 티켓의 의견 섹션은 관련 사람들이 특정 충돌에 대해 토론 할 수있는 플랫폼을 제공합니다.

이러한 각 티켓의 해상도는 디자인과 일치하도록 구현을 변경하는 것이지만 구현과 일치하도록 디자인을 변경하는 것도 가능합니다. 이상적으로 전자가 선호되지만, 때로는 더 효율적 / 실용적 / 나중을 선택할 수있게하는 기술적 및 / 또는 비즈니스 제약이 있습니다. 이 경우 아키텍처 설계 문서에서 티켓을 참조하는 것이 좋습니다. 따라서 특정 열등한 디자인 선택이 선택된 이유를 이해하지 못하는 미래의 독자는 티켓의 토론을 읽고 그 이유를 이해할 수 있습니다. 그것.

3 가지 주요 섹션으로 구성된 건축 문서를 작성하는 경향이 있습니다.

처음에 디자인 / 아키텍처를 처음 소개했습니다. 이를 통해 새로운 개발자 / 리더는 시스템이 무엇을해야하는지에 대한 아이디어를 얻을 수 있으며 요구 사항 / 사용 사례 등에 분명히 묶여 있어야합니다.

두 번째 섹션에서는 아키텍처가 실제로 무엇인지 매우 명확하게 설명해야합니다 . 이를 통해 새로운 개발자 / 리더는 현재 플레이 상태 및 소프트웨어 (및 잠재적으로 다른 문서)를 볼 때 다루고있는 것에 대한 아이디어를 얻을 수 있습니다. 이 섹션은 원래 아키텍처에 너무 잘못되었거나 (아마 많지는 않지만) 바로 가기 / 해킹이있는 영역 (아마도 상당히 적었을 가능성이 높음)으로 의도 된 것과 실제 의 차이점을 명확하게 나타내야합니다 . 개발자 팀에 대한 상당한 압력이 가해졌으며 요구 사항이 충족되지 않거나 소프트웨어가 '나쁘고'약해 지거나 불안정하고 휴대하기 어려운 디자인으로 보이기 시작했습니다.

마지막으로 지금해야 할 일에 대한 권장 사항을 자세히 설명하는 섹션을 생각합니다. 비전이 현실이 되려면 아키텍처 / 디자인에 대한 변경 사항과 현재 소프트웨어 변경에 대한 로드맵이어야합니다.

나는 이것이 캡처되어야 할 것을 (높은 수준으로) 다룬다 고 생각한다. 사용하는 문서 또는 버그 추적 소프트웨어의 하위 섹션에서이 작업을 수행하는 방법은 작업 환경 / 개인 환경 설정 / 팀 규모 / 예산 / 시간 규모 등입니다.