연결 코드 구조 및 아키텍처 문서

Question

의 난 (내가이 예를 들어 TFTP를 사용합니다) 새로운 통신 프로토콜을 작성하고 난 다음 표를 워드 문서에 있어요 가정 해 봅시다 (형식은 다를 수 있음) :

Opcode | 2 bytes 
filename | string 
padding | 1 byte = 0 
mode  | string 
padding | 1 byte = 0 

내가 코드를 작성 갈 때

지금, 나는과 같이 구조의 일종을 만드는 것입니다 : 나는 몇 가지 반복적 인 일을하고 같은 날 것으로 보인다

class TFTP_packet: 
    short opcode 
    string Filename 
    byte padding=0 
    string mode 
    byte padding2=0 

. 지금은 속도를 높이기 위해 정규 표현식을 사용하고 있지만이 데이터를 캡슐화하여 문서에 쉽게 표시 할 수 있고 코드로 쉽게 변환 할 수있는 방법이 있습니까? 문서에서 구조물을 분리 할 수있는 방법이 있습니까?

Answer 1

사양 (프로토콜)은 코드에서 수행해야 할 작업을 정의합니다. 그것은 자주 변경되어서는 안되며, 코드 버그가 스펙 버그가되지 않도록 소스에서 스펙을 생성하는 것을 원하지 않을 것입니다.

케이스 도구는 세부적인 디자인을 유지하고 동기화 된 소스를 생성하지만 거의 성공하지 못합니다. 그 길을 선택하면 그걸로 행운을 빈다. 일반적으로 디자인 문서는 초기에 코드를 개발하는 데 사용되지만 아카이브에 대한 유지 관리되지 않은 역사적인 결과물이됩니다.

반면에 최신 문서는 필요에 따라 자주 코드에서 비교적 쉽게 생성 할 수 있습니다. javadoc (java) 또는 doxygen (C++) 등이 있습니다. 여기서 성배는 실제로 콘텐츠의 모든 단일 비트 (말장난 없음)를 단일 소스로 가져 와서 최종 제품을 생성하는 것입니다. 즉, 두 개 이상의 장소에서 동일한 설명, 동일한 테이블, 동일한 데이터 구조를 유지하기를 원하지 않습니다. 그렇다고 모든 것을 한 곳 (원본 XOR)에 문서화해야한다는 것은 아닙니다. 오히려 소스에서 생성 된 내용을 문서의 기존 외부 문서로 병합하려고합니다.

그러나이 단계를 더 진행하기 위해 Word (유연하지 않음, 플랫폼 의존, 자동화하기 어렵다) 대신 OpenOffice (LibreOffice) "마스터"문서 (*.odm)를 사용하는 것이 좋습니다. 정규 문서 (*.odt)를 병합하고 & 텍스트 조각 (소스 코드 또는 테스트 프로그램 입출력에서 생성 된 이미지)을 생성하십시오. 결과 문서를 작성하는 것은 (pdf 생성을 포함하여) 스크립팅되거나 전체 소스 코드 빌드 프로세스에 통합 될 수 있습니다.