반드시 복잡한 코드 구조를 어떻게 문서화합니까?

수학적으로나 구조적으로 매우 복잡하고 돌이킬 수없는 코드 조각이 있다면이 코드 조각을 어떻게 문서화해야합니까? 특히, 수학 또는 건축 기술이없는 사람이 문서에서 이해할 수 있도록하려면 어떻게해야합니까? 모든 수학도 문서화해야합니까? 튜토리얼 링크? 복잡한 구조의 경우 시각 보조 장치가 연결됩니까?

이것은 실제로 코드와 수학이 얼마나 복잡한 지에 달려 있습니다. 코드 자체는 항상 가능한 한 자체 문서화되어야합니다. 변수의 이름을 올바르게 지정하고, 메가 함수가 아닌 논리적이고 간결한 메소드를 구현하고, 적절한 위치에 코드를 추가하십시오 (예 : 실제로 코드의 실제 동작이 확실하지 않은 경우).

명확하지 않은 알고리즘을 사용하는 경우 소스에 대한 참조에 대한 링크를 추가하십시오. 이는 개발자에게 수행중인 작업을 매우 빠르게 찾을 수있는 합리적인 방법입니다. 내가 말했듯이, 이것은 명백하지 않지만 복잡한 알고리즘 인 경우 유용합니다. 이것은 (a) 당신이 이해하는 일을하고 있고, (b) 누군가 그것이 효과가 있다는 것을 증명했음을 증명해야합니다.

좋은 예는 퍼지 텍스트 일치와 관련하여 수행 한 작업입니다. 알고리즘에 대한 실질적인 연구를 수행 한 후 'Smith-Waterman 알고리즘'(실제로는 DNA 서열에 사용되지만 일반적으로 '일치'에 적용됨)을 구현했습니다. 그래서 단순히 알고리즘을 구현하는 대신 온라인에서 참조를 발견하고 링크를 포함 시켰습니다. 위와 같이 (a) 내 알고리즘이 게시 된 알고리즘과 일치하고 (b) 알고리즘이 검토되어 작동하는 것으로 나타났습니다.

그러나 이것이 코드의 작동 방식과 다양한 클래스의 동작을 반드시 설명하는 것은 아닙니다. 시스템에 대한 개발자 안내서 인 '실제'문서를 작성할 때는 수행 한 작업을 설명하고 향후 지원을위한 충분한 정보를 제공해야합니다. 제 생각에는이 문서는 기술적으로 불가지론적인 사람이 읽을 수 있어야합니다. '멍청한'것은 아니지만 전문 용어를 배제하고 가정 된 지식에 의존해서는 안됩니다.

소스를 둘러싼 의견이 가장 먼저해야합니다. 이를 통해 코드로 문서에 직접 연결되는 링크를 찾을 수 있습니다. 문서가 매우 복잡한 경우 주석에 초록 만 게시 한 다음 아키텍처 / 복잡한 알고리즘에 대한 자세한 설명이 포함 된 일부 외부 문서에 대한 링크를 고려하십시오. 그러나 너무 복잡하지 않은 경우 모든 문서를 한 곳에 포함시키는 것이 좋습니다. 이렇게하면 코드 / 문서가 동기화 상태를 유지하고 함께 읽을 가능성이 극대화됩니다.

팀 / 회사가 필요로하는 범위까지 코드를 문서화하십시오. JR이라면. dev는 코드를 유지하기 위해 필요할 것입니다. 수학에 대해 자세히 설명해야 할 수도 있습니다. 이것은 관리 결정이며 필요한 시간을 제공해야합니다.

나는 당신이 코드를 너무 많이 문서화하여 더 적은 개발자로 대체되어야한다고 생각하지 않습니다. 이것이 우려되는 경우 문서화 할 시간이 필요합니다.

웹 검색을하지 않아도됩니다.