코드 문서:얼마나 많은가요?

https://stackoverflow.com/questions/288298

08-07-2019
|

문제

.NET 소스의 코드 문서가 너무 많습니까?

일부 배경:나는 여기에 SO에 게시한 다른 질문 중 일부에서 언급한 대규모 코드베이스를 상속받았습니다.이 코드베이스의 "기능" 중 하나는 수십 개의 정적 메서드를 포함하는 3000줄 이상의 코드가 포함된 단일 정적 클래스인 God 클래스입니다.그것은 모든 것에서 Utilities.CalculateFYBasedOnMonth() 에게 Utilities.GetSharePointUserInfo() 에게 Utilities.IsUserIE6().다 좋은 코드야 다시 작성할 필요가 없습니다, 적절한 라이브러리 세트로 리팩터링되었습니다.나는 그것을 계획해 두었습니다.

이러한 방법은 새로운 비즈니스 계층으로 이동하고 있고 이 프로젝트에서 나의 역할은 다른 개발자의 유지 관리를 위해 시스템을 준비하는 것이므로 견고한 코드 문서화에 대해 생각하고 있습니다.이러한 메소드에는 모두 좋은 인라인 주석이 있지만 모두 XML 주석 형식의 좋은(또는 임의) 코드 doco가 있는 것은 아닙니다.GhostDoc과 Sandcastle(또는 Document X)의 조합을 사용하면 꽤 멋진 HTML 문서를 만들어 SharePoint에 게시할 수 있습니다. 이를 통해 개발자는 코드 자체를 탐색하지 않고도 코드의 기능을 더 자세히 이해할 수 있습니다.

코드에 포함된 문서의 양이 늘어날수록 코드를 탐색하는 것이 더 어려워집니다.나는 XML 주석이 코드를 더 단순하게 만드는 것보다 유지 관리하기 더 어렵게 만들지 궁금해지기 시작했습니다. //comment 각 방법에 대해 설명합니다.

이러한 예는 문서 X 샘플에서:

        /// <summary>
        /// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
        /// </summary>
        /// <returns>A new Customer instance that represents the new customer.</returns>
        /// <example>
        ///     The following example demonstrates adding a new customer to the customers
        ///     collection. 
        ///     <code lang="CS" title="Example">
        /// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
        ///     </code>
        ///     <code lang="VB" title="Example">
        /// Dim newCustomer As CustomersLibrary.Customer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith")
        ///     </code>
        /// </example>
        /// <seealso cref="Remove">Remove Method</seealso>
        /// <param name="Title">The customers title.</param>
        /// <param name="FirstName">The customers first name.</param>
        /// <param name="MiddleInitial">The customers middle initial.</param>
        /// <param name="LastName">The customers last name.</param>
        public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName)
        {
            // create new customer instance
            Customer newCust = new Customer(Title, FirstName, MiddleInitial, LastName);

            // add to internal collection
            mItems.Add(newCust);

            // return ref to new customer instance
            return newCust;
        }

그리고:

    /// <summary>
    /// Returns the number of %Customer:CustomersLibrary.Customer% instances in the collection.
    /// </summary>
    /// <value>
    /// An Int value that specifies the number of Customer instances within the
    /// collection.
    /// </value>
    public int Count
    {
        get 
        {
            return mItems.Count;
        }
    }

그래서 나는 당신에게서 궁금했습니다.문서를 작성하시나요? 모두 NDoc(RIP) 또는 Sandcastle과 같은 것을 사용하려는 목적으로 코드에 XML 주석이 포함되어 있습니까?그렇지 않은 경우 무엇이 문서화되고 무엇이 문서화되지 않는지 어떻게 결정합니까?API와 같은 것에는 분명히 doco가 있지만 유지 관리를 위해 다른 팀에 넘겨줄 코드베이스는 어떻습니까?

내가 어떻게 해야 한다고 생각하세요?

해결책

여기서 문제의 좋은 부분은 MS가 우리를 향한 장점과 crufty XML 문서화라고 생각합니다 (Javadoc도 훨씬 나아지지 않았습니다). 그것을 포맷하는 방법에 대한 문제는 적절한 양과 무관하게, 큰 정도입니다.

주석에 XML 형식을 사용하는 것은 선택 사항입니다. Doxygen 또는 다른 형식을 인식하는 다른 도구를 사용할 수 있습니다. 또는 자신의 문서 추출기를 작성하십시오. 합리적인 일을한다고 생각하는 것만 큼 어렵지 않으며 좋은 학습 경험입니다.

얼마나 어려운지에 대한 질문. 코드를 유지하기 위해 파고 있다면 자체 문서화 코드에 대한 아이디어는 괜찮다고 생각합니다. 클라이언트 인 경우 주어진 기능의 작동 방식을 이해하기 위해 코드를 읽을 필요가 없습니다. 물론 많은 정보가 데이터 유형과 이름에 암시되지만, 그렇지 않은 것은 많은 정보가 있습니다. 예를 들어, 객체에 대한 참조를 전달하면 예상되는 것을 알려주지 만 Null 참조가 처리되는 방법은 아닙니다. 또는 OP의 코드에서 인수의 시작 또는 끝에있는 공백이 어떻게 처리되는지. 나는 있다고 믿는다 멀리 문서화되어야하는 이러한 유형의 정보의 더 많은 것이 일반적으로 인식됩니다.

나에게는 기능의 목적뿐만 아니라 기능, 인수 및 반환 가치에 대한 사전 및 사후 조건을 설명하기 위해 자연어 문서가 필요합니다. 프로그래밍 언어 구문을 통해 표현할 수 없습니다.

다른 팁

코드를 부풀릴 필요가 없다고 언급 한 사람은 아무도 없으며 XML 문서는 다른 파일에있을 수 있습니다.

/// <include file="Documentation/XML/YourClass.xml" path="//documentation/members[@name='YourClass']/*"/>

그런 다음 추가 방법에 추가 XML/주석이 포함되어 있거나 요약 만 선호하는 경우 (별도의 파일과 병합 된)가 포함될 수 있습니다.

PHP/JavaScript에서 찾은 Javadoc 및 파생 상품 인 쓰레기 형식보다 훨씬 강력합니다 (Javadoc은 XML 구문의 길을 열었습니다). 또한 사용 가능한 도구가 훨씬 우수하며 도움말 문서의 기본 모양이 더 읽기 쉽고 사용자 정의하기 쉽습니다 (Doclets를 작성하고 해당 프로세스를 Sandcastle/DocProject/NDOC와 비교하여 말할 수 있습니다).

새 라이브러리를 유지할 수있는 사람들과 새 라이브러리를 소비 할 사람들 사이의 비판적 분열을 치고 있습니다.

새 응용 프로그램을 작성하고 이러한 표준 라이브러리를 사용하는 경우 라이브러리의 안정적인 바이너리를 가져 와서 소스 코드를 위치에서 복사하지 않고 코드가 문제를 일으키지 않고 응용 프로그램으로 간단히 가져와야합니다. 수정됩니다. 이 경우 메소드 이름 및 입력/출력 매개 변수 이외의 "자체 문서화"기능에 액세스 할 수 없으며, ID의 ID를 사용하는 경우 노출되지 않습니다. 자동 완성 기능이 켜져 있지 않습니다.

위의 예제 코드에서는 괜찮아 보인다고 생각합니다. 코드 자체 내에서 상황이 너무 장점이 아니며 이름은 자체 문서화입니다. 반면에, 필요한 모든 요약/매개 변수 데이터가 있으므로 도서관이 소비하는 사람들이 손가락 끝에 모든 중요한 정보를 가질 수 있도록 견고한 문서 조각을 구성 할 수 있습니다. 안타깝게도 XML은 다소 부풀어 오르지 만 대부분의 개발자는 모든 요약 내용에 의해 쉽게 탐색하고 방법 내 실제 코드를 살펴볼 수 있다고 생각합니다.

Jeff는 여기에 댓글을달라고 말하는 것에 대한 정말 좋은 기사를 가지고 있습니다.

http://www.codinghorror.com/blog/archives/001150.html

나는 그것이 질문에 대답하지 않는 것처럼 보이지만, 코드가 가능한 한 자체 문서화되어야한다는 유효한 시점이라고 생각합니다.

나는 모든 공개 방법을 내 자신의 코드로 문서화하는 경향이 있습니다. Ghostdoc을 사용하면 이것이 사소합니다. 소스 코드를 편집 할 때 혼란을 줄이기 위해 일반적으로 먼저 "개요 모드"로 이동하여 주석을 무너 뜨립니다 (즉, Visual Studio의 개요를 사용하여 정의 명령으로 붕괴).

나는 Sandcastle을 시도한 적이 없지만 XML-Commented 방법에 대해 Intellisense가 제공 한 안락함에 정말 감사합니다.

API 문서를 현명한 형식 (일반적으로 html)으로 찾는 것을 좋아하기 때문에 항상 XML / Javadoc 형식 주석을 선택합니다.

실제 소스 코드를 탐색하는 데 문제가되지만 Visual Studio는 일반적으로 필요에 따라 XML 댓글을 무너 뜨리는 것에 대해 일반적으로 똑똑하기 때문에 이것은 일반적으로 사소한 문제라는 것을 알게됩니다.

자신을 반복하지 마십시오.

첫 번째 예제는 더 나은 메소드 이름과 주석이 없어야합니다.
두 번째 예제에는 의견이 없어야합니다.

첫 번째 방법의 이름은 새 개체가 할당되었음을 반영해야합니다.

해당 동작이 각 추가의 프레임 워크 전반에 걸쳐 표준 인 경우이 방법 API 문서가 아닌 더 높은 수준으로 문서화해야합니다. 그렇지 않으면 이름을 변경하십시오.

주석은 정보를 추가하고 소음으로 숨기지 말아야합니다. XML에 필요한 경우 의견이 있어야합니다. 그리고 그들이 가치를 더하는 곳.

나는 다음과 같이보고 싶지 않다 : count라는 메소드의 "count를 반환한다".

모든 공개 기능은 코드 기반에 익숙한 사람이지만 코드를 조사하지 않고는 특정 섹션에서는 안된 사람이 명확하게 이해할 수 있어야합니다.

함수가 무엇을하는지 설명하기 위해 짧은 줄을 작성 해야하는 경우 기능/클래스의 이름을 제대로 이름을 지정할 가능성이 있습니다. 이 경우 이름은 자기 설명이어야합니다

설명하기 위해 간단한 문장이 하나 이상 필요하다면 아마 좋은 의견 일 것입니다.

단락이 필요하다면, 당신의 기능은 아마도 불분명 한 이름 외에 너무 많은 일을하고있을 것입니다.

일반적으로 댓글 측면에 오류가 더 낫습니다. 그들이 정확한지 확인하는 경우. 부정확하고/또는 인사 할 수없는 의견은 의견이없는 것보다 더 나쁩니다.

따라서이 규칙을 적용하십시오.

첫 번째 예에서 : "// 새 고객 인스턴스 생성"은 중복됩니다. 코드는 명확합니다. 다른 의견은 완벽합니다. 그들은 코드가 무엇을 작동하고 있는지/그것이 무엇인지 분명합니다.

두 번째 예에서 의견은 노력을 낭비하고 읽기가 어렵습니다. 당신이해야 할 일은 기능에 올바른 이름을주기 만하면됩니다. 그 모호한 "수"가 아닙니다. 그것은 이름 지정이 좋지 않습니다.

나는 최근에 중요한 "지시문"을 가지고 있다면, 발신자는 많은 사양 내에서 x를 수행해야한다는 연구를 수행했습니다 (예 : "이 방법은 x를 수행하는 x를 수행합니다. 독자들은 지침을 놓칠 것입니다. 사실, 긴 문서를 볼 때, 그들은 그것을 읽는 것을 건너 뜁니다.

따라서 최소한 중요한 것들을 분리하거나 태깅을 사용하십시오 (Java를 사용하는지 물어보십시오).

모두 회사에서 사용하는 표준에 따라 다르지만 저희 팀에서는 두 번째 예와 같이 모든 기능의 맨 위에 문서를 기록합니다(Visual Studio 2008에서는 "/" 키를 3번 눌러 수행할 수 있음). 하위 또는 기능 상단에 연속으로!!).

첫 번째 예는 과잉입니다. 특히 각 줄에 주석이 달린 맨 아래 두 줄이 그렇습니다.하지만 함수 헤더에 있는 내용은 여기에서 많이 사용하기 때문에 유용할 수 있다고 생각합니다.그리고 그것은 제가 다른 많은 프로그래머들로부터 알 수 있는 것과는 다소 표준적인 것 같습니다.

댓글 자체화 코드 및 메소드 오버로드에 대해 추천하는 코딩 표준을 보았습니다. YMMV이지만 "Field _numberofcars는 자동차의 수를 나타내는 정수"에서 벗어나는 좋은 방법처럼 들립니다.

문서를 생성하기위한 헤더의 의견은 좋은 것입니다. 왜 당신이하고있는 일을하는지 설명하기 위해 코드에 의견을 두는 것도 일반적으로 좋은 일입니다. 당신이 한 일을 말로 표현하는 중복 된 의견을 넣는 것은 좋지 않습니다.

당신이 보여준 것은 너무 많습니다. 자신에게 호의를 베풀고 삭제하십시오!

코드는 먼저 의미있는 방법과 매개 변수 이름을 통해 자체 문서화해야합니다. 당신이 보여준 예에서;

공개 고객 추가 (제목 제목, String FirstName, String MiddleInitial, String Lastname)는 'Count'와 같이 일어나는 일의 의도에 완벽하게 이해할 수 있습니다.

당신이 지적했듯이 이와 같은 댓글은 순전히 소음 코드를 읽기 쉬운 것 주위. 대부분의 개발자는 모호한 자동 생성 API 문서를 통한 파일보다 코드를 더 빨리 검사하고 사용합니다. 매번!

그건 그렇고, "Clean Code"(Great Book, BTW)에 따르면 소스 코드에 내장 된 주석 내에 HTML/XML 마크 업을 사용하지 않아야합니다. IDE가 호버 할 때 멋진 문서를 만들 수 있다고해도 소스를 탐색 할 때 너무 산만하고 읽을 수없는 것으로 간주됩니다.

라이센스 : CC-BY-SA ~와 함께 속성

제휴하지 않습니다 StackOverflow