문서 성능 저하-처리 방법?

중요 : 우리가하지 더 문제 와 어떠한 소스 코드 문서를 . 이것은 정기적 인 코드 감사에 속하며 최신 상태로 유지됩니다. 우리의 문제는 개발자 문서 (또는 원하는 경우 "외부"), 프로그래머에서 프로그래머가 작성하는 경향이있는 블로그와 같은 작은 팁과 관련이 있습니다.

우리는 위키와 같은 시스템을 사용하여 프로그래머 문서 를 작성 합니다. 프로그래머가 특정 코드가 어떻게 작동하는지 좀 더 자세하게 설명 하기 위해 프로그래머가 작성한 기사 입니다. 이러한 위키 페이지에는 일반적으로 다음이 포함됩니다.

• API의 일부에 대한 디자인 결정에 대한 동기 부여 (예 : 이 특정 타사 라이브러리는 이런 방식으로 작업을 수행하기를 원하기 때문에이 추한 일을했습니다 .이 라이브러리는 ...이기 때문에 ...)
• 특정 공통 작업을 처리하는 방법에 대한 설명 (예 : 적절한 응용 프로그램 스타일을 참조하고 레지스트리 구성 요소에 등록하고 다른 구성 요소에 의해 자동으로 "스캔"되도록 일부 인터페이스를 구현해야하는 간단한 팝업 표시)
• 좋은 관행
• 환경 구성, 필수 도구 및 설정

일반적으로 크기 및 블로그 게시물 / 문서와 같은 특성으로 인해 정기적 인 코드 문서화에 맞지 않는 코드 작성과 관련된 것들입니다.

문제

몇 달 전이 시스템을 도입하는 것이 좋은 생각 인 것처럼 요즘에는 시스템이 해결하는 것보다 더 많은 문제를 일으키는 것 같습니다. 예를 들면 다음과 같습니다.

• 사람들 은 기사를 쓰지만 ... 일단 코드가 변경되면 위키 업데이트는 거의 따르지 않습니다.
• 많은 스크래치 기사, 서둘러 누군가에 의해 쓴처럼 왼쪽
• 기사 요청은 일반적으로 프로젝트 리더가 제공하지만 정확성 / 조성에 대한 검증은 거의 이루어지지 않아 때로는 품질이 떨어집니다.

일반적인 저하. 코드가 변경되었으며 위키는 동일하게 유지됩니다. 다음에 누군가 정보를 찾을 때, 일반적으로 그가 발견하는 것은 오래되고 품질이 낮은 것들입니다. 그리고 그가 찾은 것이 정확한지 또는 더 나쁜지에 대해 궁금해하고 있습니다. 그리고 도움이 되었어야했던 것은 정반대입니다.

현재 사람들이 문제를 알고 있고 프로젝트 리드가 포함 된 것으로 보이지만 아무도 그 문제를 다루는 데 신경 쓰지 않는 것 같습니다 (또는 더 흥미로운 일을하고 있음).

나의 초기 생각은 모든 것을 망각에 던져 넣는 것이었다 (내가 구식 "팁"에 몇 번 연속 물린 후에), 나는 그것이 너무 극단적이라고 생각합니다. 일부 정보는 가치가 주목할 좋은 가끔 읽어하지만 문제는 여전히 동일합니다 : 당신은 그것의 처리 방법 "최신" ? 어떻게 든 소스 코드에 링크되어 있습니까 (따라서 업데이트 된 버전의 파일을 체크인하면 기사 작성자가 코드 / 기사를 수정해야 할 수도 있음을 알립니다)? 지정된 사람이 매일 기본 사항에 대해 "감시"했습니까? 정기적으로 청소합니까?

위키에서 너무 많은 퀴즈를 문서화하는 것처럼 들립니다.

코드의 코드 블록과 메소드를 문서화하십시오 . 코드를 자체 문서화하여 많은 주석을 작성할 필요가 없도록하십시오. 단위 테스트 작성도 도움이 될 수 있습니다.

위키에서 세분화 하여 디자인 결정 및 아키텍처를 문서화 하므로 위키는 자주 변경하거나 변경하기 위해 많은 작업을 수행 할 필요가 없습니다. 팀의 많은 사람들이 이미 아키텍처를 알고 있고 팀이 빠르게 성장하고 있지 않다면 문서화에 대한 강력한 사례가 없을 수도 있습니다. 대면은 종종 최고의 지식 이전입니다.

데드 코드와 같이 오래 지속되면 정보를 찾기가 어려워지고 누적되는 정보가 많을수록 오래된 정보를 즉시 다시 쓰거나 삭제하십시오 . 시간이 없다면 기사를 삭제하고 기사를 재 작업이 필요하다고 표시하면 속도가 느려지고 어쨌든 버전 관리에 저장됩니다.

스크립트 나 설치 파일로 절차를 자동화하여 문서화 하십시오. 그렇지 않으면 위키에 보관하십시오. 그러나 누군가 위키의 프로 시저를 사용할 때마다 기사를 개선하거나 프로세스의 일부를 자동화하도록 지시하십시오.

블로그 기사는 블로그에 속합니다 . 사람들이 자신의 의견과 조언을 공유하려면 회사 블로그를 만드십시오. 그들은 아마도 기사를 수정하기를 원하지 않을 것이며 아무도 수정하지 않을 것이므로 위키를 혼란스럽게 만들지 마십시오.

문서는 제공 가능한 것으로 취급되므로 개발 시간과 적절한 시간이 주어질뿐만 아니라 추적 성 및 수용 규칙을 준수해야합니다.

사람들이 소프트웨어 문서를 "예상"하는 것이 좋지 않은 경우가 종종 있습니다.

과격하지만 효과적입니다. 누군가 새 모듈을 작성했지만 문서화하지 않은 경우 문제 추적기에서 작업을 다시 열고 필요한 경우 문서화되지 않은 소스 코드를 모두 배송하지 못하게합니다. 개발자가 소스 코드 문서를 필요한 악으로 취급 할 수있게되면 단편적이고 오래된 문서 조각이 생길 수 있습니다.

최근 프로젝트에서 우리는 최소한 필요한 모든 타사 라이브러리를 추적하는 경향이 있습니다. 누군가 새로운 라이브러리를 소개하지만 문서화되지 않은 경우 문서가 소개 될 때까지 솔루션을 롤백합니다. 그러한 급진적 인 접근이 없다면 혼란이 생길 ​​것입니다. 예를 들어, 경험이없는 개발자는 라이센스가 소프트웨어 라이센스와 충돌하는 라이브러리를 사용할 수 있습니다.

무언가가 빠르게 변하는 경우 코드 외부에서 유지해서는 안됩니다.

API의 일부에 대한 디자인 결정의 동기

이것은 코드에 가깝게 유지하는 데 특히 중요합니다. 같은 소스 파일에서와 같이. 이렇게하면 누군가 파일을 만질 때마다 무시하고 외부 문서가 존재하는지 모르는 사람들이 TheDailyWTF에 제출하는 횟수를 줄이기가 더 어려워집니다.

일반적인 저하. 코드가 변경되었으며 위키는 동일하게 유지됩니다.

여기서 "실행 가능한 문서"(단위 테스트)가 매우 유용합니다. 코드가 변경되고 테스트가 변경되지 않으면 빌드가 중단됩니다. 물론 문서로 테스트를 작성하려면 약간의 기술이 필요합니다. 그러나 외부 문서를 작성하는 것도 좋습니다.

문제를 처리하는 좋은 방법은 프로세스의 일부로 만드는 것입니다. 위키에서 관련 페이지를 추적하거나 참조하는 코드가있는 경우 개발자는 업데이트해야 할 내용을 쉽게 찾을 수 있습니다. 또한 리뷰어가 코드 업데이트를 담당하도록하여 업데이트와 관련하여 위키가 최신인지 확인하십시오.

프로세스의 일부로 모델을 추가하는 또 다른 방법은 반복 계획 프로세스의 일부인 애자일 모델을 사용하므로 위키에서 계획된 변경 사항을 업데이트하는 것입니다. 그런 다음 위키는 '이것이 어떻게 작동해야 하는가'리소스 역할을합니다.

.net 언어를 사용하는 경우 XML 문서 (C #에서 ///)를 MSDN 도움말 형식으로 변환하는 ( Sandcastle )을 보십시오 .

형식에는 설명, 설명이 포함되며 코드 샘플과 기타 기능을 포함 할 수 있습니다. .CHM, .HsX, .MSCH 및 HTML / ASP.NET 형식으로 출력 할 수 있습니다. 실제 프로젝트가 솔루션에 추가되고 빌드 서버에서 빌드됩니다. 우리는이 작업을 수행하고 모든 릴리스마다 웹 사이트에 배포했으며, 소비자는 문서가 릴리스와 관련이 있고 지속적으로 업데이트되기 때문에 웹 사이트를 좋아합니다.

설명서에 포함 할 내용을 지정할 수도 있습니다. 현재 2 개의 프로젝트가 있습니다. 하나는 계약 및 적절한 항목 (클래스, 열거 형 등) 만 포함하는 외부 소비자 용 프로젝트와 비공개 및 내부 플래그가 지정된 항목을 포함하여 API의 모든 것을 포함하는 내부 개발자 용 프로젝트입니다.

API 사용에 대한 동기와 단점이 문서의 주석 섹션에 포함될 수 있으므로이 문서는 우리가 사용하는 유일한 문서가되었습니다. 프로세스는 내가 일하는 곳에서 잘 작동합니다.

두 가지 영역에 중점을 둘 것입니다. 1) 코드. 2) 없음 코드 메모 및 문서.

1) 코드.

자체 문서화를 시도하십시오. 과거에는 자주 조언을 받았지만 잘 설명하지는 못했습니다.

이런 종류의 의사 코드 대신 :

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

다음과 같은 코드를 작성하십시오.

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

'누가 언제 무엇을했는지'정보를 추적하려면 소스 컨트롤을 사용하십시오.

2) 비 코드

이 정보를 유지하려면 위키 및 마크 다운 형식을 사용하십시오. 작업의 일부로 만드십시오. 게시하고 게시하고 블로그에 게시하십시오. 기존의 주별 또는 월별 회의를 설정하여 이전 및 새 항목을 검토하십시오. 누군가가 무언가에 대해 물었을 때 대답은 "만약 다음에 누군가가 요청할 때 위키에 있어야합니까?"라는 생각과 함께 만트라로 만드십시오.