기존 코드베이스를 문서화하는 방법론

인라인 문서가 없거나 기술 문서가없는 기존 응용 프로그램에서 팀의 일원으로 일하고 있습니다. 응용 프로그램에 대한 다양한 버그 보고서를 작성하면서 다음 장소에서 버그 번호를 작성하여 다음 개발자가 해당 버그 번호를 참조하여 진행 상황을 확인할 수 있습니다.

내 질문은 따라서 :

이 코드를 문서화하는 가장 효율적인 방법은 무엇입니까? 해당 영역을 터치 할 때 문서화해야합니까 (바이러스 검사 방법 인 경우), 각 섹션에서 자체적으로 문서화해야하고 응용 프로그램의 다른 영역으로 분기되는 경로를 따라 가지 않아야합니까? 이전에 존재하지 않은 곳에 인라인 주석을 삽입해야합니까 (코드가 무엇인지 잘못 식별 할 우려가 있습니다)?

기존 인라인 문서가 없거나 외부 문서에 대한 인라인 참조가없는 다소 큰 응용 프로그램을 정확하고 신속하게 문서화하는 데 어떤 방법을 사용 하시겠습니까?

레거시 코드베이스 문서화

레거시 코드 기반으로 스카우트 규칙 을 따르는 것이 좋습니다 . 기존 프로젝트와 독립적으로 레거시 프로젝트를 문서화하는 것은 결코 일어나지 않을 것입니다.

코드 내 문서

가장 중요한 것은 선택한 개발 환경에서 문서화 기능을 사용하는 것입니다. 따라서 파이썬 용 pydoc , Java의 javadoc 또는 C #의 xml 주석 을 의미합니다. 이를 통해 코드 작성과 동시에 문서를 쉽게 작성할 수 있습니다.

나중에 돌아와서 문서를 작성하는 데 의존한다면, 그 문제를 해결하지 못할 수도 있지만 코드를 작성하면서 코드를 작성하면 문서화해야 할 것이 마음에 새겨질 것입니다. C #에는 XML 문서가 불완전하거나 실제 코드와 일치하지 않는 경우 컴파일 경고를 발행 할 수도 있습니다.

문서로 테스트

또 다른 중요한 측면은 통합 및 단위 테스트가 우수하다는 것입니다.

종종 문서는 클래스와 메소드가 독립적으로 수행하는 작업에 중점을 두어 문제 해결을 위해 함께 사용되는 방법을 건너 뜁니다. 테스트는 종종 서로 상호 작용하는 방식을 보여줌으로써 상황에 맞게 배치합니다.

유사하게, 단위 테스트는 종종 외부 의존성을 지적하여 어떤 것들을 모의해야하는지 명시 적으로 지적합니다.

또한 테스트 중심 개발 을 사용하면 go라는 단어에서 바로 사용하기 때문에 사용하기 쉬운 소프트웨어를 작성 한다는 것을 알았습니다. 좋은 테스트 프레임 워크를 사용하면 코드를 쉽게 테스트하고 사용하기 쉽게 만드는 것이 종종 같은 일입니다.

더 높은 수준의 문서

마지막으로 시스템 레벨 및 아키텍처 문서에 대해 수행 할 작업이 있습니다. 많은 사람들이 위키에서 문서를 작성하거나 Word 또는 다른 워드 프로세서를 사용하는 것을 옹호 할 것이지만, 나에게 그러한 문서를위한 가장 좋은 장소는 코드와 함께 버전 관리 시스템 친화적 인 일반 텍스트 형식입니다.

코드 내 문서와 마찬가지로 상위 수준의 문서를 코드 저장소에 저장하면 최신 상태로 유지할 가능성이 높습니다. 또한 코드의 버전 XY를 가져올 때 설명서의 버전 XY도 얻을 수 있다는 이점이 있습니다. 또한 VCS 친화적 형식을 사용하는 경우 코드와 마찬가지로 분기, 확산 및 병합이 쉽다는 것을 의미합니다.

html 페이지와 pdf 문서를 쉽게 생성 할 수 있고 LaTeX 보다 훨씬 친숙 하지만 여전히 필요할 때 LaTeX 수학 표현식을 포함시킬 수 있기 때문에 나는 rst를 매우 좋아 합니다.

까다로운 질문입니다. 기본적으로 "리팩토링"방법을 사용합니다. "리터 링"방법을 사용합니다.

그러나 정확하게 말하면; 문제가 발생하고 발생하는 버그를 수정하기 위해 코드에 익숙해 져야 할 때, 그 코드에 대한 주석을 작성하려면 그 친숙성을 사용해야합니다. 본질적으로, 버그를 수정하려는 동기는 그 시점에서 코드를 문서화 할 수있는 코드를 충분히 익히도록 강요했습니다. 그리고 그 이유로 인해 관련되지 않은 분기를 따르거나 관련없는 함수를 문서화하는 것에 대한 우려가 있습니다. 코드의 기능과 이유를 정확하게 이해해야합니다. (버그 수정을 테스트 할 때에도 코드가 무엇을, 왜 어떤 역할을하는지 정확하게 파악하기가 어렵다는 문제에 봉착하지 않았습니다.

이 접근 방식은 전체 속도를 희생하면서 정확도를 최대화하는 경향이 있지만 동시에 코드를 너무 심각하게 유지해야 할 필요성에는 영향을 미치지 않습니다. 물론 버그 수정 업무가 적다면, "알 수없는 영역"으로 들어가서 문서화를 시작할 수 있지만 (대부분의 우리처럼) 코드를 수정하고 문서화 할 수있는 충분한 시간을 찾을 수 없다면 좋은 타협입니다.

한가지 주목할 점이있다. 좋은 외부 문서가 있어야합니다. 코드에 외부 문서에 대한 참조가 없다고 말합니다. 그래도 그러한 외부 문서가 존재하기를 바랍니다. 그렇지 않다면, 나는 실제로 그 외부 문서를 최우선으로 작성하려고합니다. 기능 사양의 수준에있는 것은 모든 대규모 소프트웨어 프로젝트에 절대적으로 중요하다고 생각합니다. 그 이유는 기능 사양 또는 해당 형식의 고급 문서가 모든 소프트웨어에서 "기능 크리프"또는 "피처 드리프트"를 방지 할 수 있기 때문입니다. 피처 드리프트 (특히)는 문서가 오래 될 수 있으므로 문서를 손상시킬 수 있습니다. (나는 소프트웨어의 조각에 대한 기능의) 진보 (성가신 또한 같은 기능 크리프를 정의, 기능 드리프트반면에 소프트웨어가 수행하는 일련의 작업은 시간이 지남에 따라 천천히 변경됩니다. 기능 크리프는 부가 적입니다. 즉, 일반적으로 소프트웨어의 기능 세트를 증가시킵니다. 반면에 피처 드리프트는 0 합입니다. 소프트웨어가 원래 의도 한 것과 완전히 다른 것을 수행 할 때까지 하나의 엣지 기능은 다른 것을 수행하도록 정의됩니다. 특징 드리프트는 드물지만 문서화에는 치명적입니다.)

2 년 동안 공동 개발 한 응용 프로그램 중 하나에는 문서화가 심각하지 않았습니다. 어느 시점에서 우리는 응용 프로그램을 그 시점부터 유지 관리하려는 다른 개발자에게 전달할 것이 분명해 졌으므로 코드를 문서화해야했습니다.

문서화 프로세스의 거대한 범위를 다루기 위해 특정 기능이나 앱의 일부에 모든 코드를 주어진 날에 문서화하려고 시도했습니다. 나는 특별한 패턴이 없었지만 매일 매일 어떤 일을하고, 전체 파일이나 앱의 섹션을 매일 문서화하여 완성 감을 얻었습니다.

전체 응용 프로그램을 문서화하는 데 몇 달이 걸렸지 만 하루 30 분 (최대)에 프로젝트 일정에 실제로 참여하지 않았고 문서화와 관련된 많은 지루함을 피했습니다.

우리는 C #에서 XML 문서를 사용했으며 문서화를 쉽게하기에 충분한 기능과 구조를 제공했습니다. C # 앱을 문서화하지 않더라도 간단한 요약을 먼저하고 그 다음에 언급하는 패턴은 매우 유용했습니다.

코드를 추가 / 수정할 때 문서화합니다. 그 외에도 공개 API 또는 모듈 간의 인터페이스를 문서화하려고합니다. 모든 코드를 문서화해야하는 경우 시간 동안 ROI가 표시되지 않을 수 있습니다. 외부 문서를 개발할 때 위키와 같은 것을 사용하여 외부 문서를 구성하는 것이 유용 할 수 있습니다. 마지막 프로젝트를 시작할 때 가장 유용한 문서는 아키텍처 문서였습니다. 여기에는 사용 된 기술에 대한 정보가 포함되었으며 응용 프로그램 계층화 방법에 대한 높은 수준의 시각을 제공했습니다.

나는 Doxygen 의견을 사용합니다. Doxygen은 대부분의 다른 무료 형식보다 더 많은 출력 형식을 가지며 배우기 쉽습니다.

우리 중 일부는 생계를 위해 계약을 체결하는 것을 고려할 수도 있습니다. 그러나이 선택으로 여전히 문서를 검토 할 것을 약속해야합니다.

또 다른 일반적인 기술은 코드를 문서화하는 데 새로운 개발자를 할당하는 것입니다. 그런 다음 각 새로운 사람이 속도를 낼 때마다 통과하도록하십시오. 일부 개발자는 이것을 직접 근관에서만 필요한 근관을 얻는 것으로 간주합니다. LOL.

문서화를 시작하기 전에 표준을 개발하십시오. 이것은 함수 또는 클래스 헤더 위에 몇 줄을 더 공식적이고 장황한 것 (javadoc과 같은)으로 작성하는 것만 큼 간단 할 수 있습니다. 누구나 코드를 체크인하려면 문서가 해당 표준을 충족해야합니다.

내가 찾은 것은 이전에 문서화되지 않은 함수에 함수 헤더 앞에 잘 작성된 주석을 추가하고 내가 추가 한 모든 것에 인라인 주석을 추가하는 것입니다. 만지지 않은 코드를 문서화하지 않으려 고합니다. 의견이없는 것보다 나쁜 의견을 갖는 것이 나쁘고,이 '빠른'을 문서화하는 경우 나쁜 의견을 쓰게 될 것입니다.