왜 그렇게 많은 라이브러리에 문서가 없거나 부족합니까? [닫은]

디자인이나 아키텍처에 대한 문서없이 오픈 소스 프로젝트를 성공적으로 수행 하는 방법 과 비슷한 맥락에서 ? 질문, 궁금합니다 : 왜 최종 라이브러리에 너무 많은 라이브러리가 부족합니까?

내 견해는 이것이다 :

1. 대부분의 사람들은 소스 코드를 읽는 것이 소스 코드를 쓰는 것보다 어렵다는 데 동의합니다.
2. 문서가 없으면 해당 라이브러리를 사용하려면 라이브러리의 소스 코드를 읽어야합니다.
3. 따라서 문서화되지 않은 라이브러리를 사용하는 것은 라이브러리를 처음부터 다시 작성하는 것보다 더 많은 작업입니다.
4. 결과적으로 사람들이 라이브러리를 사용하게하려면 문서화가 잘되어 있어야합니다.

많은 개발자가 문서 작성을 좋아하지 않으며 지루한 작업이 될 수 있음에 동의합니다. 그러나 그것은 필수적인 작업입니다. 심지어 세계 최고의 프로그래머의 인터페이스보다 라이브러리에 좋은 문서가있는 것이 더 중요하다고 말하고 싶습니다. (사람들은 항상 칙칙한 라이브러리를 사용하고 문서화되지 않은 라이브러리를 사용하는 사람은 거의 없습니다)

아, 내가 문서를 말할 때, 나는 실제 문서를 의미합니다. Sandcastle / Javadoc / Doxygen 상용구가 아닙니다.

대부분의 경우 개발자가 귀찮게하지 않기 때문에 자신의 질문에 대부분 대답했다고 생각합니다. 이 문제는 특히 자원 봉사 프로젝트에서 널리 퍼져 있습니다.

그래도 또 다른 큰 문제가 있다고 생각합니다. 많은 경우 개발자가 실제로 라이브러리 작동 방식에 대한 전반적인 모델을 개발하지 않았거나 해당 모델을 명확하게 표현하기가 어렵습니다. 불행히도, 모델을 설명하고 소프트웨어 조각이 어떻게 어울리는지는 종종 문서의 가장 중요한 부분입니다.

일반적인 경우, 작성된 내용은 매우 높은 수준의 개요 ( "이것은 멋진 작업을위한 라이브러리입니다!")와 매우 낮은 수준의 설명 (각 함수에 전달 될 각 매개 변수의 유형 및 설명)을 갖습니다. 불행히도 사물이 어떻게 작동해야하는지, 조각들이 어떻게 어울리는 지 등에 대한 일반적인 이론에 대한 중간 수준은 거의 없습니다. 특정 세부 수준의 코드. 적어도 내가 본 몇몇 경우에, 그 수준에서 문서를 작성하도록 요청받은 개발자들은 많은 문제를 발견했습니다. 많은 사람들이 코드를 다시 작성하기를 원했기 때문에 그 수준에서 더 체계적이고 설명하기 쉽습니다. 세부 묘사.

해당 추상화 수준에서 글을 작성하는 것은 종종 어렵습니다. 개발자가 해당 추상화 수준에서 실제로 생각 하지 않으면 코드가 다소 난처 해져서 행복하기 전에 다시 작성하고 싶을 수도 있습니다. 그것을 발표하는 것에 대해.

개발자가 코드에 싸서 작동 방식에 대해 "명백한"이유 때문에 다른 사람에게 왜 명확하지 않은지 알 수없는 경우가 있습니다. 마찬가지로 많은 제품 웹 사이트에서 제품이 얼마나 훌륭한 지 말하지만 실제로 제품의 기능을 알려주지는 않습니다.

당신은 대답을 스스로 지적했습니다.

많은 개발자가 문서 작성을 좋아하지 않으며 지루한 작업이 될 수 있음에 동의합니다.

프로그래머로서 우리는 코드 작성을 좋아하지만 문서 작성을 좋아하는 사람은 거의 없습니다.

좋은 코더는 좋은 문서의 가치를 알고 있지만 제대로하는 데 상당한 시간이 걸립니다. 즐겁지 않고 오랜 시간이 걸리기 때문에 "나중에 할 일"더미에 들어가므로 만족스러운 수준으로 끝나지 않습니다.

참고로 프로그래머가 자체 제품에 대한 문서를 작성하는 것은 매우 어렵습니다. 그들이 시스템을 잘 알고 있기 때문에 어떤 것이 분명합니다. 이러한 부분은 소비자에게 명백하지 않더라도 종종 언급되지 않습니다.

문서 작성은 기술입니다. 모든 기술과 마찬가지로 연습이 필요합니다. 우리가 코드를 작성하는 데 드는 시간과 노력은 즉시 보상을받습니다. 새로운 기능, 수정 된 버그, 향상된 속도를 볼 수 있습니다. 문서 작성에 지연이 있습니다. 새로운 사람들이 코드 작업을해야하거나 코드 또는 코드 작업을 몇 개월 또는 몇 년 후에 다시 시작해야하는 경우 장기적으로 도움이됩니다. 우리가 단기에 집중하는 것은 당연합니다.

내 의견으로는, 좋은 문서를 작성하는 능력은 훌륭한 프로그래머와 평범한 프로그래머를 구별하는 주요 특성 중 하나입니다.

문서 작성에 가장 적합한 사람은 다음과 같은 동기 부여가 가장 적은 사람이기도합니다.

그 (또는 그녀)는 :

• 주로 사용자가 아닌 라이브러리의 관리자입니다. 따라서 라이브러리가 작고 단순할수록 작업이 쉬워집니다. 코드 외에 소설 을 절반 만 유지하면 작업이 더 어려워집니다.
• 그는 도서관 내부를 알고 있기 때문에 문서 가 필요 하지 않습니다 .
• 그는 프로그래머이며 문서가 아닌 코드를 작성하려고합니다.

나는 "흠, 나는 이것에 대한 적절한 문서를 작성하는데 몇 시간을 소비해야한다"고 생각할 가능성이 적은 사람 을 생각할 수 없다 . 왜 그럴까?

물론, 자동 생성 된 독소 스타일 주석이 문서 측면에서 필요한 모든 것입니다.이 도시 전설이 도움이되지는 않을 것입니다.

따라서 개발자가 실제로 문서를 기꺼이 쓰는 드문 경우에도 개발자 가이 컬트에 의해 세뇌되어 필요한 모든 것이 주석을 채우고 보석 같은 "함수 Foo getFoo()는 Foo 유형의 객체를 반환하고 Foo 객체를 얻는 데 사용됩니다".

선적 서류 비치? 우리는 악의적 인 문서가 필요하지 않습니다!

코드의 작동 방식을 알고 있으므로 코드를 문서화하는 데 왜 시간을 소비합니까? 그 외에도 금요일 까지이 프로젝트를 완료해야하며 그대로 유지하려고합니다 ...