모든 것을 문서화하거나 가장 많이 문서화해야합니까?

그것은 필드에 대한 getter 및 setter의 "자바 빈즈"구문을 포함하여 문서의 모든 것에 대한 논란 대상의 비트를 보인다 : 사람들이 말하는 그 불필요하게 길고 반복적 인 차단 DRY (중복 배제) , 명명 규칙을 설명해야 모든 것을 , 코드 / 문서가 복잡해집니다. 때로는 그러한 주장이 효과가 있습니다. 그러나 다른 경우에는 다음과 같이 끝납니다.

위의 원칙은 이러한 원칙을 과감하게 따르는 오픈 소스 프로젝트에서 일반적입니다. 당신은 완전히 쓸모없는 문서를 남겼습니다 . 그것은 무슨 일이 일어나고 있는지, 가능한 효과, 또는 예상되는 값에 대해 설명하지 않습니다 (널이거나 null이 될 수 있습니까? 모르겠습니다 .Javadoc은 나에게 말하지 않습니다).

언제 문서를 작성해야합니까? 때때로 코드가 복잡 해지더라도 모든 것을 문서화합니까? 아니면 내 눈에 "명백한"것이기 때문에 아무 것도 기록하지 않습니까?

문서화 하기에 적합한 모든 것을 문서화하십시오 .

이상적인 세상에서는 모든 것을 문서화해야합니다. 그러나 지구상에는 마감일, 기능 삭감, 가족 및 친구 방문, 휴가, 하루 24 시간, 연중 365 일만 있습니다. 모든 것을 문서화 할 시간이 충분하지 않습니다. 따라서 최선을 다해 가능한 모든 것을 문서화하십시오 (완료되지는 않음).

• 문서화가 덜 필요할 수 있도록 코드를 읽을 수 있고 메소드 서명을 가능한 분명하게 만드십시오 .
• 가장 모호한 것을 먼저 문서화하십시오. 문 밖으로 나가기 위해해야 ​​할 미친 해킹을 문서화하여 다른 사람들을 도와주세요.
• 문서화 왜 전에 무엇을 - 음주 "잔고가 제로보다 작은 및 평가가 덜 하나보다하고 exemptCustomers 목록에 추가 어디 고객 레코드를 반복"뭔가처럼, 무엇을 언급하지. 문서 왜 당신이 고객이 음의 균형과 낮은 등급을 가지고 있기 때문에 같은 "그들이 우리가 돈을 잃게하는 원인이되어, 일반 영어 (또는 팀의 언어)의 목록에 추가된다, 그래서 체크 아웃 할 수있는에서 제외.

다른 사람이 설명 할 필요없이 다른 사람이 읽을 수있게 될 때까지 문서를 작성하십시오.

지난주 에 The Daily WTF에서 문서화에 관한 훌륭한 기사 가있었습니다 . 나는 그것이 모든 것을 말한다고 생각합니다. 그래서 나는 링크를 남겨 둘 것입니다 :

http://thedailywtf.com/Articles/Documentation-Done-Right.aspx

기본적으로 유용하지 않을 경우 무언가를 문서화해서는 안되며 (일부 문서는 서랍에서 썩어 버릴 수 있습니다) 프로젝트의 특정 부분을 이해하는 데 필요한 최소한의 정보를 문서화해야합니다. 너무 많은 문서는 독자를 혼란스럽게합니다.

코드를 읽는 사람이 코드를 읽을 수있는 정도에 달려 있습니다. 청중이 귀하의 코드를 읽는 사람을 파악하고 해당 프로파일을 충족하는 사람이 귀하의 코드를 읽도록하십시오.

또 다른 방법은 일주일 후에 자신의 코드를 검토하고 수행 한 작업을 여전히 이해하고 있는지 확인하고, 그렇지 않은 경우 코드를 문서화하고 2 주 정도 후에 코드를 검토하는 것입니다.

명확하고 광범위한 문서에 감사하지만 자체 문서 코드와 같은 것은 없습니다. 따라서 결론은 다음과 같습니다.

(소스 코드) 문서를 매우 의심하십시오. 코드를 개선하여 중복을 시도하지만 필요할 때 명확하고 완벽하게 문서화하지 마십시오.

물론 특정 상황에서 '코드가 무엇을하는지 설명하는 것'이외의 이유로 문서가 필요할 수 있습니다 (예 : 대규모 팀 기반, 조직 표준 등).

문서에 대한 제안은 코드에 멋진 것이 있으면 최신 상태로 유지 해야하는 문서에 속한다는 것입니다. 공상은 많은 해석을 필요로합니다. 제 생각에는 주목해야 할 부작용이있을 수있는 특정 방식으로 무언가가 수행되는 곳입니다. 모든 후손들에 대한 테스트를 수행합니다. 왜 무언가가 특정한 방식으로 이루어 졌는지를 분명히하는 것은 무언가를 사용해야 할 이유가 있는지를 알 수있는 좋은 방법이 될 수 있습니다.

간단히 말해 설명서는 현재 개발자와 미래의 관리자에게 도움이됩니다.

간단한 최대 값을 기억한다면 문서 수준은 스스로 정의해야합니다.

문서화를 위해 문서화는 시간 낭비입니다. 그러나 현재하고있는 일을 설명하는 것이 5 년 안에 코드를 리버스 엔지니어링해야하는 사람보다 도움이됩니다.

개인적으로 나는 모든 것을 문서화하는 것을 고려 하는 접근법을 사용합니다 . 즉, 코딩하는 동안 모든 시점에서 문서가 가치를 추가하는지 고려합니다. 원래의 질문에서 언급 한 제약과 영역 지식의 종류에 대한 답은 대부분 그렇습니다. 예를 들어, 널 (null) 기능, 고유 제한 조건, 더 넓은 영역의 필드 해석

중복을 피하기 위해 이런 종류의 정보로 주요 API 클래스를 많이 문서화하는 경향이 있습니다. 그런 다음 명확하지 않거나 일관되지 않은 동작이있는 구현 및 내부 만 문서화하십시오. 가장 도움이 필요하고 문서가 필요한 API 사용자이므로 이것이 잘 작동한다는 것을 알았습니다. 구현을 수정하는 사람들이 API를 알고 있으므로이 지식을 가지고 있다고 가정하는 것이 일반적으로 안전합니다.

또한 게터 만 문서화하는 경향이 있습니다. 세터, 필드 정의 및 생성자 매개 변수에 설명서를 복제하지 않습니다. 나는이 장소에서 기본값과 같은 명백하지 않은 행동 만 문서화합니다. 게터 문서에서 유추 할 수있는 동작은 문서화되어 있지 않습니다. 예를 들어, getter가 null을 반환하지 않는 것으로 문서화 된 경우, 기본값이 없으면 setter에 null을 전달할 수 없다고 일반적으로 문서화하지 않습니다.

어떤 사람들은 문서를 고려했지만 불필요하다고 생각되는 곳에 빈 주석을 추가하여 "문서 고려"의이 행위를 표시하는 것을 좋아합니다. 코드를 어지럽히고 방해하기 때문에이 연습이 마음에 들지 않습니다.