주석 작성 및 문서화 모범 사례

요즘 댓글 달기가 훨씬 쉬워졌습니다. Java에는 주석을 클래스에 연결하는 멋진 기술이 있으며 Java IDE는 주석 쉘을 만드는 데 능숙합니다. Clojure와 같은 언어를 사용하면 함수 코드 자체에 함수 설명을 인수로 추가 할 수도 있습니다.

그러나 우리는 여전히 훌륭한 개발자들이 쓸모 없거나 열악한 의견이있는 시대에 살고 있습니다. 저는 제 의견의 견고성과 유용성을 개선하는 데 관심이 있습니다.

특히 Java / Clojure / Python에 관심이 있지만 언어별로 답변 할 필요는 없습니다.

주석의 유효성을 검사하고 "매끄러운"주석 (예 : 마법 번호가있는 주석, 불완전한 문장 등) 또는 잘못된 주석 (예 : 철자가 틀린 변수 등을 감지)을 자동으로 감지하는 새로운 기술이 있습니까?

그리고 더 중요한 것은 "설명 정책"이나 전략이 있습니까? 코드 작성 방법에 대한 많은 조언이 있지만 "주석 처리 방법"은 어떻습니까?

• 이름은 / 문서는 당신에게 말해야 무엇을 당신이하고 있습니다.

• 구현 방법 을 설명 해야 합니다.

• 의견은 왜 그렇게하는지 알려줘야합니다 .

이것은 논란의 여지가 있지만 가능한 한 FEW 의견을 작성하는 것이 좋습니다. 대신 깔끔하고 명확한 클래스 이름, 변수 이름 및 메소드 이름을 사용하십시오. 가능한 가장 명확한 방법으로 코드를 작성하십시오. 그리고 이것이 코드의 가장 중요한 속성이라고 생각하십시오 (요구 사항을 충족시키는 것 이외). 가능한 한 명확하게 방법을 만들었을 때만 의견을 쓰십시오. 그래도 추가 설명이 필요하다고 생각합니다.

그리고 어떤 방식 으로든 수업을 변경할 때마다 의견이 모두 올바른지 확인해야하는 조직적인 관행을 갖습니다.

다른 언어에 대해서는 잘 모르겠지만 파이썬을 사용하면 자체 유효성 검사 의견의 한 형태 인 doctest 를 작성할 수 있습니다 . 물론 실제 단위 테스트 대신 사용해서는 안되지만, 명확하지 않은 특정 기능을 문서화하는 빠르고 쉬운 방법입니다. 그들은 주석이 여전히 올바른지 확인하기 위해 주석 테스트를 실행할 수 있다는 추가 이점을 제공합니다 (적어도 테스트를 포함하는 부분).

문서를 자동으로 생성하기 위해 코드 주석을 사용하는 방법 을 찾는 가장 권위있는 위치 중 하나 는 반드시 doxygen 입니다. 그런 도구를 더 많이 얻을 수 있었지만.

이것은 문서를 자동으로 생성하기 위해 따라야하는 주석 작성 표준을 정의합니다 . 그러나 이것은 더 많은 구조를 제공하지만 의미 적으로 검증되지는 않습니다. 예를 들어 함수의 목적을 설명하기 위해 오도하는 영어를 사용했는지 확인할 수 없습니다!

이것은 주석을 구조화하는 가장 좋은 방법이지만 개인적으로 코드를 유지 관리하기 쉽게 만드는 데 더 많은 문서가 필요하다고 생각합니다. 과거에는 P.SE에 질문이있었습니다. 코드가 오픈 소스 개발자 도구의 문서가 될 수 있습니까? 얼마나 자주? 물론 이것은 오픈 소스가 아닌 프로젝트에도 적용됩니다.

코드를 유지 관리하기 쉽게하려면 코드를 처리하는 방법의 구조를 만드는 데 도움이되는 외부 문서가 있어야하며 코드 내부의 주석은 제한되어 있어야합니다.

주석 작성 정책을 정의 하려면 코딩 표준에 포함 된 전체 론적 접근 방식으로 포함시켜야한다고 생각합니다. 개발팀에 스타일 가이드와 문서를 생성하는 소프트웨어를 도입 할 때 어떤 함정 이 있을 수 있습니까?

일반적으로 주석은 코드의 5 % 미만을 구성합니다. 실제로 코드 검토 자체는 (다른 개발 측면에 비해) 덜 주목을받는 반면 주석도 검토하기가 실제로 어렵습니다.

주석의 유효성을 검사하고 "매끄러운"주석 (예 : 마법 번호가있는 주석, 불완전한 문장 등) 또는 잘못된 주석 (예 : 철자가 틀린 변수 등을 감지)을 자동으로 감지하는 새로운 기술이 있습니까?

잘 알려진 기술이 있습니다. "코드 검토"라고하며 "pair-programming"이라는 자매가 있습니다. 여기서 "자동적으로"는 기대하지 마십시오.

그리고 더 중요한 것은 "설명 정책"이나 전략이 있습니까? 코딩하는 방법에 대한 많은 조언이 있습니다. "-어떻게 주석을 달까요?"

"Code complete" 에는 코딩 방법뿐만 아니라 "주석 달기"장, 특히 자체 문서화 코드 작성 방법에 대한 장도 포함되어 있습니다.

내가 즐겼던 Java의 한 가지 소스 는 Javadoc 도구에 대한 Oracle의 Doc Comments 작성 방법입니다 .

이 문서는 Sun Microsystems의 Java Software에서 작성된 Java 프로그램의 문서 주석에 사용되는 스타일 안내서, 태그 및 이미지 규칙을 설명합니다.

그리고 항목 44 : 노출 된 API 요소에 대한 쓰기 다큐 멘 테이션 코멘트 :

API를 사용하려면 문서화해야합니다. 전통적으로 API 문서는 수동으로 생성되었으며 코드와 동기화 된 상태를 유지하는 것이 번거로운 일이었습니다. Java 프로그래밍 환경은 Javadoc 유틸리티를 사용하여이 작업을 용이하게합니다. Javadoc은 일반적으로 문서 주석이라고하는 특수 형식의 문서 주석이있는 소스 코드에서 API 문서를 자동으로 생성합니다.

에서 효과적인 자바 2 판 .