코드 문서를 자동 생성해야하는 논리적 이유가 있습니까? [닫은]

자동 문서 생성은 다양한 도구를 사용하여 수행 할 수 있으며, GhostDoc은 더욱 두드러집니다. 그러나 정의에 따라 생성되는 모든 것은 중복됩니다. 메소드, 클래스 등의 이름을 살펴보고 더 자세하게 설명 할 수있는 영어를 출력 합니다. 가장 좋은 경우, 독자가 이미 머리에서 할 수있는 일을 수행합니다 ( 여기 에서 가져온 예 ).

/// <summary>
/// Initializes a new instance of the <see cref="Person"/> class.
/// </summary>
public Person() ...

최악의 경우, 실제로 이름의 의미를 발견 적으로 시도하려는 시도에서 실제로 오해의 소지가있는 기괴한 문서를 생성 할 수 있습니다.

/// <summary>
/// Riches the text selection changed.
/// </summary>
/// <param name="richTextBox">The rich text box.</param>
private void RichTextSelection_Changed(System.Windows.Controls.RichTextBox richTextBox) ...

GhostDoc의 태도는 " 어떤 종류의 공식적인 XML 문서 를 갖는 것이 본질적으로 더 낫습니다"라고 생각 되지만 문서가 100 % 중복 된 이유는 무엇입니까? 그것은 단지 많은 공간을 낭비하지 않습니까?

직장에서는 모든 것을 문서화해야하며 거의 항상 GhostDoc의 자동 생성 문서를 사용해야합니다. 실제로 문서를 직접 작성하지 않을 경우 코드를 문서화하지 않은 합리적인 이유가 있습니까?

[...] 모든 것을 문서화하고 거의 항상 GhostDoc의 자동 생성 문서를 사용하십시오. 실제로 문서를 직접 작성하지 않을 경우 코드를 문서화하지 않은 합리적인 이유가 있습니까?

아닙니다. GhostDoc에 의해 생성 된 문서는 상용구입니다 (IDE에서 새 OO 클래스를 생성하는 것이 생성자 등으로 클래스에 대한 boileplate을 생성하는 방법과 유사합니다). 문서의 유용한 부분은 상용구를 추가 한 후 따라야 할 내용입니다.

직장에서 모든 것을 문서화 해야 하지만 동료가 주변에서 완벽한 방법을 찾은 것 같습니다.

정적으로 유형이 지정된 언어에서 Javadoc 스타일 문서는 작성자를위한 것이 아니라 소비자를위한 것입니다. 자동 생성을 통해 작성자는 다른 사람이 사용할 수 있도록 문서를 쉽게 유지할 수 있습니다.

정적으로 유형이 지정된 언어를 사용하고 있고 타사 사용을 위해 라이브러리를 작성하지 않는 경우 자동 생성은 많은 비용을 들이지 않으며 제 경험상 거의 사용되지 않습니다. 동적으로 유형이 지정된 언어를 사용하는 경우 내부 용도로만 유형을 문서화하는 데 javadoc 스타일 문서가 종종 사용되지만 자동 생성은 유형을 알지 못하므로 보일러 플레이트를 수동으로 복사하지 않아도됩니다.

어느 쪽이든, 자동 생성은 완제품을 생산하는 것으로 생각하지 마십시오. 상용구를 생산하는 것으로 생각하면 수동으로 변경 한 내용이 중요합니다.

코드 문서를 자동 생성해야하는 논리적 이유가 있습니까?

누구의 관점에서?

회사 나 개발자 그룹을 운영하고 있다면 그럴만한 이유가 없습니다. 나는 "설명은 왜 야영을 설명 해야하는지 "에 푹 빠졌다 . 사람들이 클래스 / 함수 / 속성을 언급하도록 강요하는 것은 가치가없는 것보다 더 나쁘다. 그들은 구식이되어 독자를 오도하고, 읽을 수있는 코드를 만들지 않는 변명으로 사용된다. 이 주석은 코드를 작성하고 코드를 읽고 버그로 인해 시간을 낭비합니다. 어떤 사람들은 JavaDoc 스타일 API 문서가 주석을 작성하는 이유라고 주장하지만, 그 주장조차도 코드의 작은 부분은 공개 API의 일부 여야하며 JavaDoc은 실제 API 문서를 대체하지 않습니다.

개발자로서 저는 제 의견에도 불구하고이 장소에서 의견 이 필요한 몇 곳을 작업했습니다 . 아무도 사용하지 않을 쓰레기를 쓸 시간이나 인내심이 없기 때문에 대신 GhostDoc을 사용하십시오. 이를 통해 실제로 중요한 일을하는 데 시간을 할애 할 수 있습니다. 회사 정책을 변경하는 것보다 훨씬 효율적입니다.

GhostDoc을 사용하여 찾은 또 다른 좋은 점은 내 이름이 좋은지 확인하는 것입니다. GhostDoc이 함수에 대한 적절한 문서를 생성 할 수 없다면, 함수 또는 매개 변수 이름이 좋지 않은 냄새가납니다. 나는에 대한 도구를 사용하지 않을 동안 만 이 내가 어쨌든 내 시간을 낭비 이루어지고있어 경우, 그것은 좋은 작은 부작용입니다.

편집 : 나는 원래의 질문을 오해했다; 문서 (예 : 비 코드 문서 )를 생성하는 것이 매우 가치가 있다고 생각하지만 ( 아래의 Doxygen에 대한 원래 답변 참조) 자동 생성 주석 (GhostDoc이 실제로하는 것)은 나에게 미치게 들립니다. 프로그램이 주석 처리되지 않은 소스 코드를 읽고이를 명확하게 설명하는 주석을 작성할 수있는 이유를 아무도 이해할 수 없습니다.

매우 "스마트 한"주석 생성 유틸리티 는 특정 패턴을 인식하고 "어떻게"스타일의 주석을 생성하도록 프로그래밍 될 수 있음을 생각할 수 있다. 예를 들어 Knuth의 분산 계산 알고리즘을 인식 하고 작동 방식과 순진 알고리즘이 적합하지 않은 이유를 설명 할 수 있습니다. 아마도 이러한 유틸리티는 표준 객체 지향 디자인 패턴 (예 : 추상 팩토리)을 인식하고 어떤 패턴이 사용되고 있는지, 어떤 클래스가 어떤 역할을하고 있는지 나타내는 주석을 삽입하도록 프로그래밍 될 수도 있습니다.

그러나 제 의견으로는, 가장 유용한 주석은 코드 자체가 이것을 보여줘야하기 때문에 "어떻게"작동 하는지를 설명하지는 않지만 " 왜 "주석은 특정 이유를 설명합니다. 아래의 주석에서 David Hammen이 언급 한 것처럼 "이유"주석을 생성하려면 유틸리티가 "프로그래머의 마음을 읽어야합니다". 분명히 이것은 불가능합니다.

그러나 주어진 예를 바탕으로 GhostDoc은 진정한 "방법"스타일 주석을 작성하는 작업을 수행하지 않는 것으로 보입니다. 무엇 이후 그래서, 쓸모보다 더 내 의견에서, 않습니다 생성하는 것은 어리석은와 (두 번째 예에서와 같이) 오해의 소지가 될 수 있습니다.

원래 답변 : 자동 문서 추출 및 서식 이 좋은 이유

내 소프트웨어 팀은 Doxygen을 사용합니다. 이것의 주된 이유 는 코드 기능 / 행동 / 등에 대한 비 소스 코드 (즉, 프로그래머가 아닌 사람이 읽을 수있는) 문서가 필요하지만 이를 소스 코드 자체에 통합하는 것이 더 나은 방법이라고 생각합니다. 두 번째 문서로 유지하십시오 . 이를 통해 문서를 소스 코드와 동기화 상태로 유지할 수 있습니다 (물론 완전히 보장 할 수는없고 자동화 수준은 낮음). 문서 작성의 오버 헤드를 최소화합니다 (코드에 대한 문서를 간단하게 통합 할 수 있으므로). 코드 자체를 포함하는 파일).

따라서 Doxygen 사용의 초점은 코드 자체에서 정보를 추출하는 것이 아니라 소스 코드 문서를 소스 코드 자체에 최대한 가깝게 유지하는 것입니다.

또한 하나의 단일 도구를 사용하여 전체 코드베이스를 설명하는 "작동 이론"과 소프트웨어 제품을 설명하지만 실제로 "코드 문서"를 포함하지 않는 "릴리스 노트"세트를 만들 수 있습니다. 전형적인 의미.

코드 동작에 대한 비 소스 코드 문서가 필요한 이유는 두 가지 이유가 있습니다.

• 우리의 제품은 단순한 소프트웨어가 아닙니다. 멋진 레이저 및 유체 공학을 포함하여 많은 하드웨어 구성 요소를 통합하는 복잡한 도구입니다. 코드 내부가 어떻게 동작하는지 정확하게 이해 하고 "소스 코드를 읽습니다"라고 말하는 것은이 작업을 수행하지 않을 소프트웨어가 많지 않은 엔지니어가 필요 합니다.
• 우리는 회사가 내부적으로 규정하고 일부는 연방 정부가 법적으로 규정 한 품질 규정을 준수해야합니다. 품질 프로세스는 매우 중요하고 도움이 될 수 있지만 무시할 수없는 양의 오버 헤드가 수반되며,이 중 일부는 소프트웨어 팀이 소프트웨어에 대한 자세한 종류의 세부 문서를 제공해야합니다. 이 문서를 코드 자체와 통합하면 오버 헤드가 최소화되고 문서를 최신 상태로 유지할 수 있습니다.

두 번째 글 머리 기호는 모든 소스 코드에 대해 일부 문서 (품질에 관계없이)가 존재한다는 사실을 알고 안심할 수있는 관리자에 대해 몇 가지 다른 답변을 제시 한 점과 매우 유사합니다. 그러나이를 구성하는 방식은 외부에서 규정 한 문서가 실제로 몇 가지 정당한 이점을 가질 수 있다는 사실을 무시합니다.

확실히 자동화 된 문서는 코드 작성자가 작성한 통찰력 있고 적절한 설명을 재현 할 때 특히 유용합니다. 그렇지 않으면 영광스러운 자동 포맷터 일뿐입니다.

그러나 서식은 쓸모가 없습니다. 하나의 시선에서 지연 구성 요소의 공개 방법을 찾을 수 있고, 분류되고, 완벽하다는 것이 가치가 있습니다. frobnick뮤 테이터 가 필요하고 거기에 없으면 뮤 테이터 가 소스 코드를 넘어 가지 않고 존재하지 않는다는 것을 알고 있습니다. (부정적인 결과도 가치가 있습니다. 무언가를해야한다는 것을 알고 있으며, 포기할 필요가 없기 때문에 더 많은 시간을 할애 할 수 있습니다.)

예, 자동 문서 생성은 약간의 가치를 더 합니다. 확실히 관리자가 생각하는 것만 큼은 아니지만 대개 훌륭한 편집자만큼 많지는 않지만 아무것도 아닙니다.

이 형식에서는 쓸모없는 것보다 나쁘지만 공개 서명에만 의존하기 때문에 (Javadoc의 경우 API 문서를 읽는 사람이라면 누구나 볼 수 있습니다).

그러나 방법의 본문도 고려하는 자동화 된 문서 도구를 작성할 수 있습니다. 개념 증명으로 문서화 된 메소드에서 Javadoc에 호출 된 다른 메소드 목록을 추가하는 lame little Eclipse 플러그인을 작성했습니다. (물론 모든 호출이 아니라 예를 들어 패키지별로 필터를 정의 할 수 있습니다.)

그리고 실제로 완전히 익숙하지 않은 코드 기반을 정신적으로 매핑 할 때 매우 편리하다는 것을 알았습니다. 물론, 그것은 매우 제한된 유스 케이스이지만 확실히 도움이되었습니다.

그 경험을 바탕으로 질문에 대한 대답은 그렇습니다. 그러나 훨씬 똑똑한 도구가 필요합니다.

업데이트 : 물론 추가 질문 (모든 종류의 문서를 작성하기 전에 질문해야 함)은 대상 독자가 누구인지입니다. 우리가 해당 API의 클라이언트에 대한 공개 API를 문서화하는 경우, Javadoc에 넣은 것은 기술적으로 API의 일부이므로이 구현 세부 사항을 모두 추가하는 것은 큰 일이 아닙니다.

그러나 대상 독자가 동일한 제품을 작업하는 다른 개발자 인 경우 특정 필드를 수정하거나 읽는 방법과 같은 구현 세부 정보에 대한 정보를 자동으로 추가하는 것은 수용 가능하고 상당히 유용합니다.

다른 환경에 대해서는 모르지만 다른 사람들이 작성한 대규모 (종종 오픈 소스) PHP 프로젝트의 경우 phpXRef는 절대 생명을 구하는 것입니다 (특히 문서가 온라인에 있고 Google이 색인을 생성 할 수있는 경우).

잘못 주석 처리 된 프로젝트조차도 적어도 정의 된 위치와 사용 위치 (예 : 리팩토링)를 추적하는 데 도움이 될 수 있습니다.

잘 언급되면 결과 페이지는 코드베이스에 대한 완벽한 성경에 가깝게 형성됩니다 (어쨌든 내 용도로).

또한 선호하는 IDE는 주석 작업의 약 75 %를 수행하는 주석 블록 (/ **를 입력하면)을 자동 생성합니다. 내가하고있는 일을 다른 사람들에게 (그리고 미래에) 설명해야했기 때문에 코더 수명 동안 커밋을 중단 한 바보 같은 일이 얼마나 놀라운 지 놀랍습니다. 문서 생성기에 대한 내 의견이 방법보다 클 때 일반적으로 커피가 충분하지 않아 조금 더 열심히 생각하고 싶을 수 있습니다.

그 자체적으로 동일한 주석 블록은 또한 인라인 완성 "도움말"텍스트를 만들어서 함수 호출을 작성할 때 (다른 코더가 예상 한 것)을 정확하게 볼 수 있습니다. 이것은 저에게 큰 생산성 향상입니다 (특히, 다른 도움이되는 개발자가 "선량을 위해 /하지 말아야 할 X"라고 쓴 드문 경우에 많은 고통을 줄일 수 있습니다.

복잡한 (그리고 종종 이름이 잘못된) PHP 프로젝트에 지정된 예상 입력 유형과 덜 자주 사용되는 메소드의 인수 순서를 지정하는 것이 얼마나 유용한 지 충분히 강조 할 수 없습니다. 내 자신의 코드를 사용하더라도 나이에 맞지 않은 것에 대해 내가 지정한 주장을 항상 기억할 수는 없습니다.

예를 들어, 반복되는 문제의 원인은 이전의 개발자들에게 잘못 반영된 어떤 이유로 인해 일부 기능과 상수가 수많은 장소에서 정의되었다는 것입니다 ( "재미"에 대한 불일치 정도). . 그것은 프로젝트에서 멀어 졌다는 신호였습니다.

내가 참여하기 전에 시작한 더 큰 프로젝트에서 어떤 개발자 (클래스 파일에 이름과 전자 메일로 태그를 지정했다고 가정)가 클래스를 생성하고 올바른 개발자를 찾아서 대화 할 수 있다는 것이 큰 도움이된다는 것을 알 수 있습니다.

자동 작업 목록-@todo 태그 (내가 작업하고있는 프로젝트 종류에서 일반적 임)를 사용하면 문서에서 더 많은 작업이 필요한 항목 (또는 누락 된 것으로 확인 된 기능)을 추적 할 수 있습니다. 다시 한 번 IDE는이를 추적하고 그 자체만으로 내주의가 필요한 것이 무엇인지에 대한 좋은 가이드 역할을합니다.

마지막으로 (그리고 나에게 매우 중요한) 그것은 모든 것을 작성하고 일부 (읽는 많은) 코더가 변경 사항을 커밋하고 문서 관리자와 이야기하지 않을 때 최신 상태로 유지하려고하는 사소한 오버 헤드를 제거합니다.

따라서 그 이유는 다음과 같습니다.

• 이후 개발자에게 시간을 절약하고
• 함수가 어디에서 호출되고 정의되는지 추적
• 바보 같은 코딩,
• 무언가 빠졌을 때 찾기 (다른 사람이 지적했듯이) 찾기,
• 리팩토링 단순화 (많은 재미는 없음)
• (많은 경우) 개발자가 무엇을하려고했는지에 대한 아이디어를 얻습니다 (어떤 메모를 남겼다고 가정).
• 프로젝트가 여러 라이센스를 계속 사용할 수있을 정도로 복잡하다면 (재미 없음) 특정 섹션에 어떤 라이센스가 적용되는지 빠르게 확인할 수 있습니다. 물론 이것은 부수적 인 보너스입니다.
• 프로젝트 파일에 대해 누가 이야기해야하는지에 대한 아이디어 얻기.
• 자동 작업 목록

또한 뾰족한 머리 보스가 버튼을 터치하여 행복하게 유지하는 가치를 과소 평가하지 마십시오.

요컨대 "자동 문서 주석"은 코딩 습관에 매우 중요합니다. 나는 그것이 절름발이라고 생각하는 많은 사람들이 있다고 확신하지만, 또한 내가 무슨 말을하는지 정확히 아는 공정한 소수의 사람들이 있다고 확신합니다. 나는 phpXRef (그리고 내가 좋아하는 IDE)를 발견하기 전에 어떻게 살아남 았는지 모른다.

문서 생성기를 사용하여 상용구 또는 "스탠드 인"주석을 작성한 다음 나중에 실제 개발자가 수정하는 것이 좋습니다. 필자는 종종 Eclipse의 auto-JavaDoc 함수를 사용하여 매개 변수 유형 및 이미 채워진 값으로 헤더 주석을 생성 한 다음 문서의 "고기"를 추가합니다.

C # 개발자로서 모든 클래스, 메소드 등에 대한 주석을 요구하는 Stylecop를 사용합니다. 도구를 사용하여 이러한 주석을 자동 생성합니다. 대부분의 경우 도구에 의해 생성 된 주석은 충분하며 개체의 이름 (예 : Person 클래스 및 ID 필드)으로 추론 될 수 있습니다.

그러나 분명하지 않은 방법을 더 언급하고 싶다면 상용구 문서를 확장하고 그 작업에 대한 몇 가지 설명을 쉽게 확장 할 수 있습니다. 예를 들어 Person 클래스에 FirstName + Lastname을 반환하는 메서드가 있지만 둘 중 하나가 없을 때 발생하는 일에 대해 약간의 문서를 추가했습니다.

간단히 말해서 : 생성기에서 제공 한 텍스트를 절대 변경하지 않으면 상용구 문서가 해로울 수 있다고 생각합니다. 이 경우에는 단지 라인 노이즈입니다. 그러나 템플릿으로 보는 경우 자신이나 소비자에게 유익하고 유용한 의견을 제시하는 기준이 낮아집니다. 주석을 자동 생성하지 않고 작성할 수 있습니까? 물론, 당신은 형식을 준수해야 할 것입니다 (C # 경우에는 다소 장황하고 수작업으로 생성하는 것이 성가시다).

긴장을 피하십시오

코드에 대한 모든 종류의 문서가 필요한 유일한 방법은 왜 메소드 / 함수가 무언가를 수행 하는지 설명 하는 것입니다. 이름은 그것이 수행하는 것에 충분합니다 .

관용적이지 않은 일을하거나 놀랍게도 되는 원칙을 어기면 문서가 필요합니다.

정보 출력을위한 포맷터 인 자동 생성 문서는 코드 소비자가 거의 요구합니다. Javadoc은 이것을 매우 잘 수행합니다.

모든 것이 수동으로 문서화되어야하는 것은 아닙니다

getXXX / setXXX 메소드와 같은 것은 자체 설명이 필요하므로 자동 생성 문서가 있음을 알려주는 자동 생성 문서가 잘 수신됩니다.

최소한 "자동"종류의 코드 문서는 응용 프로그램을 이해하려는 사람들에게 가장 일반적인 분모를 나타냅니다.

가장 정교한 사용자는 자동 코드 문서를 좋아하지 않을 것입니다. 그들은 "작은"내용을 알려주는 "타겟팅 된"문서를 가지고있을 것입니다.

가장 정교하지 않은 사용자는 반대의 이유로 그것을 이해하지 못할 것입니다. 그들은 어쨌든 그것을 이해하지 못할 것입니다.

자동 코드 문서를 가장 많이 사용하는 사용자는 "약간의 지식"이 위험한 사람입니다. 문서를 이해하지 못하거나 이해하지 못할 수도 있지만 (있는 경우에도) 이 대상은 대부분의 "관리"유형을 포함합니다. 이것이 주요 대상인 경우 자동 코드 문서가 좋은 것일 수 있습니다.

"문서를 생성하는 이유"에 대한 간단한 대답은 MSDN을 표시하여 간단히 대답 할 수 있습니다.

API 문서가없는 라이브러리를 사용하는 프로그램을 작성한다고 상상해보십시오. 악몽 일거야 MSDN은 소스 코드 및 주석에서 생성되고 개발자에게 필수 리소스를 제공 할 수있는 일종의 문서입니다.

응용 프로그램을 작성하는 경우 (즉, 다른 사람이 사용하는 라이브러리가 아닌) 귀찮게하지 않을 수도 있습니다. 그러나 큰 내부 전용 응용 프로그램에 라이브러리가 포함되어 있지 않은 정도 어쨌든? 이러한 팀에 합류 할 때 탐색 가능한 API 문서를 만드는 것이 도움이 될 것입니다.

어떤 도구도 문서를 작성하지 않지만 어쨌든 수동으로 작성 해야하는 상용구를 제공하지만 일부 도구 (doxygen과 같은)는 다이어그램 및 참조 목록 (예 : 호출 및 호출 함수)을 생성합니다 ) 소스 코드를 보더라도 쉽게 발견 할 수 없습니다.

문서화되는 것에 분명히 실용적인 상식을 적용해야하며, 속성과 작은 기능은 무시할 수 있으며 (도구에서도 생성에서 건너 뛸 수 있음), 아무 때나 "소스 코드가 충분하다"고 말하는 사람은 없습니다 .