오픈 소스 프로젝트에 대한 코드 개요가없는 이유는 무엇입니까? [닫은]

매우 복잡한 오픈 소스 프로젝트가 있으며 그중 일부에는 기여할 수 있다고 생각하지만 할 수 있기를 바랍니다.하지만 한 가지 이유로 코드를 한 줄 변경하기 때문에 진입 장벽이 너무 높습니다. 큰 프로젝트는 모든 것을 이해해야합니다.

모든 코드를 읽을 필요는 없으며 (읽더라도 충분하지는 않지만) 모든 한 줄의 모든 동작과 이유를 이해해야합니다. 코드가 모듈화되고 구식 화되어 있기 때문에 추상화가 있기 때문입니다. 그렇다하더라도 당신이 얻을 필요 개요 당신이 알 수 있도록 프로젝트를 어디 모듈은, 어디 하나 개의 모듈의 상호 연동, 수행 정확히 각 모듈이 수행하고 이유를 , 및에서를 디렉토리와 파일이 일어나는 이러한 일들의 각이다.

오픈 소스 프로젝트가 웹 사이트 또는 코드를 외부인에게 설명하는 문서에서 가질 수있는 섹션의 이름 으로이 코드 개요를 호출합니다 . 저는 잠재적 기여자들 에게 도움이 될 것이라고 생각합니다 . 그들이 구축 할 수있는 장소와 관련된 실제 주요 코더 를 식별 할 수 있고 모든 것을 쓰는 동안 마음을 재구성하고 사용자를 도울 수 있을 것입니다. 그들이 경험하는 버그를 이해하고 더 잘보고하는 데 도움이되고, 심지어 기여자가 될 수도 있습니다.

그러나 여전히 이러한 "코드 개요"중 하나를 본 적이 없습니다. 왜? 이와 같은 것들이 있는데 누락되어 있습니까? 내가 설명하는 것과 같은 일을하는 것? 아니면 나를 제외하고 모든 사람이 수천 줄의 코드로 프로젝트를 쉽게 이해할 수 있기 때문에 이것은 완전히 쓸모없는 아이디어입니까?

이러한 문서를 작성하고 유지 관리하는 데 추가 노력이 필요하고 너무 많은 사람들이 관련 이점을 이해하지 못하기 때문입니다.

많은 프로그래머들은 훌륭한 기술 저술가는 아니지만 (많은 사람들이 있지만); 그들은 사람이 소비하기 위해 엄격하게 문서를 작성하는 경우가 거의 없기 때문에 연습이없고 그것을하는 것을 좋아하지 않습니다. 코드 개요를 작성하면 코드에 지출 할 수없는 시간이 필요하고, 초기 당신이보다는 "우리는 세 가지 인코딩 변형을 지원하는"말할 수있는 경우 프로젝트에 대한 혜택은 항상 크다 "우리는 우리의 코드의 정말 깔끔한 설명을 해!" 긴 더 많은 코드를 실행한다는 점에서, 그래서 그러한 문서가 작성 얻을 것이다 더 많은 개발자를 유치한다는 개념은 정확히하지 외국 그들에게 있지만 불확실한 도박으로 인식 것; 이 텍스트가 실제로 공동 작업자를 잡는 것의 차이를 만들까요? 내가 코딩을 계속하면 지금 , 이 일을 끝내십시오.

코드 개요 문서는 사람들이 방어 적이라고 느끼게 할 수도 있습니다. 상위 의사 결정을 정당화 할 필요성을 느끼지 않고 설명하기가 어렵고, 사람들은 실제로 자신이 직접 작성할 때 "충분히 들리는"이유없이 결정을 내립니다. 앞서 언급 한 것과 관련된 효과도 있습니다. 변경되는 코드에 맞게 텍스트를 업데이트하면 추가적인 노력이 필요하기 때문에 코드의 전체적인 변경을 방해 할 수 있습니다. 때로는 이러한 안정성이 좋은 것이지만 코드에 실제로 중간 수준의 다시 쓰기가 필요한 경우 책임이됩니다.

건조하고 가혹한 진실?

프로젝트가 없으면 문서를 작성할 수 없으므로 문서화되지 않습니다.

오픈 소스 프로젝트조차 종종 경쟁이 치열합니다. 그러한 프로젝트의 대부분은 큰 어깨로 시작하지 않고 밝은 아이디어, 종종 한 사람의 밝은 아이디어로 시작합니다.

따라서, 그들은 무료로 협력하겠다고 제안 했더라도 인간 문서를 고용하는 시간과 비용을 감당할 수 없습니다. 실제로 문서화 된 프로젝트는 일반적으로 처음 몇 번의 반복을 거쳤습니다. 그것은 종종 1-3 명으로 시작하고, 아마도 5 명의 사람들이 자신의 참신한 아이디어를 적어서 개념의 증거로 세상에 보여줍니다. 아이디어가 좋은 것으로 판명되면 "추종자"가 추가 될 수 있습니다. 확장, 새로운 옵션, 번역을 요구하는 경향이 있습니다.이 시점에서 코드는 여전히 프로토 타입이며 일반적으로 하드 코딩 된 옵션과 메시지가 있습니다.

모든 오픈 소스 프로젝트가이 단계를 넘어서는 것은 아니며, 대중의 관심을 끌기 위해 필요한 "중요한 질량"을 깨는 프로젝트 만 있습니다. 또한, 초기 개발자 중 하나는 "크고 멀리 생각"하고 확장 등을 계획해야합니다. 그는 프로젝트 "전도자"가 될 수도 있고 때로는 "프로젝트 관리자"가 될 수도 있습니다 (때로는 다른 사람들입니다). 이는 개념 증명에서 산업이 확립 한 현실에 이르기까지 프로젝트를 시작하는 데 필요한 단계입니다.

그럼에도 프로젝트 관리자는 문서를 작성하지 않도록 선택할 수 있습니다.

역동적이고 성장하는 프로젝트는 느려지고 문서화는 코드보다 뒤떨어 지지만 번역, 옵션 구현, 관리자 연결을 위해 실제로 열심히 향상되고 있습니다 ...

일반적으로 발생하는 일은 다음과 같습니다.

1. 프로젝트가 무엇이며 어디로 갈 것인지에 대한 간략한 소개 문서가 작성됩니다 (유명한 "로드맵").
2. 가능한 경우 API가 개발되고 기본 코드 대부분에 대해 "문서화 된 코드"로 선택됩니다.
3. API는 물론 다른 코드도 재 형식화되고 "PHPdoc"/ "Javadoc"등 특수 주석이 추가됩니다. 그것들은 소비 된 시간과 보상 사이의 적절한 절충안을 제공합니다. 심지어 겸손한 프로그래머조차도 자신의 기능을 설명하는 하나의 라이너를 작성하는 방법을 알고 매개 변수는 "자동"으로 문서화되며 전체는 관련 코드와 연결되어 문서화를 피합니다 " desyncing "및 지연되는 behing 개발.
4. 대부분의 경우 포럼이 작성됩니다. 최종 사용자와 프로그래머가 서로 대화 할 수있는 강력한 소셜 미디어입니다 (그리고 "devs only"하위 포럼에서 동료들간에). 이를 통해 커뮤니티가 만든 (개발자 팀에 무게를 두지 않음) FAQ 및 하우투 트에 의해 많은 지식이 천천히 나타나고 통합 될 수 있습니다.
5. 실제로 큰 프로젝트에서는 위키가 생성됩니다. 나는 "대규모 프로젝트"라고 말합니다. 왜냐하면 그들은 위키를 만들만큼 충분한 추종자들이 있기 때문입니다.

설명하는 것과 같은 개요 문서는 상용 프로젝트에서도 거의 없습니다. 개발자에게는 거의 가치가없는 추가 노력이 필요합니다. 또한 개발자는 실제로 필요한 경우가 아니면 문서를 작성하지 않는 경향이 있습니다. 일부 프로젝트에는 기술 문서 작성에 능숙한 회원이있어 결과적으로 사용자 문서가 훌륭합니다. 존재하는 개발자 문서는 코드 변경 사항을 반영하도록 업데이트되지 않을 것입니다.

잘 조직 된 프로젝트는 비교적 자명 한 디렉토리 트리를 갖습니다. 일부 프로젝트는이 계층 구조 및 / 또는 선택한 이유를 문서화합니다. 많은 프로젝트가 상대적으로 표준 코드 레이아웃을 따르므로 이해하면 동일한 레이아웃을 사용하는 다른 프로젝트의 레이아웃을 이해할 수 있습니다.

코드 줄을 변경하려면 주변 코드에 대한 이해가 제한적입니다. 그렇게하기 위해 전체 코드베이스를 이해할 필요는 없습니다. 고장난 기능의 종류에 대한 합리적인 아이디어가 있다면, 디렉토리 계층 구조를보다 빨리 탐색 할 수 있습니다.

코드 줄을 변경하려면 줄을 찾는 방법을 이해해야합니다. 메소드의 예상되는 동작이 무엇인지 이해하면 수정하거나 기능을 확장 할 수 있어야합니다.

범위를 제공하는 언어의 경우 개인 범위 메소드를 리팩토링 할 수 있습니다. 이 경우 리 팩터 메소드 또는 메소드뿐만 아니라 호출자를 변경해야 할 수도 있습니다. 이를 위해서는 코드 기반에 대한 이해가 더 넓지 만 여전히 제한적입니다.

이러한 변경을 수행하는 방법에 대한 예제는 tinyca 에 SHA-2 추가를 참조하십시오 . 인터페이스를 생성하는 데 사용되는 코드에 대한 이해가 극히 제한적입니다.

이와 같은 것들이 있는데 누락되어 있습니까? 내가 설명하는 것과 같은 일을하는 것?

다양한 오픈 소스 소프트웨어 프로젝트에 대한 자세한 설명을 제공하는 오픈 소스 응용 프로그램 아키텍처 라는 훌륭한 책 이 있습니다. 그러나 나는 그것이 당신이 상상하고있는 역할을 정확하게 채우고 있는지 확실하지 않다. 나는 주요 독자가이 책에 소개 된 프로젝트에 새로운 기여자가 아닌, 자신의 응용 프로그램을 만들 때 따라야 할 패턴을 찾는 개발자가 될 것이라고 생각하기 때문이다. (나는 그것이 도움이 될 것이라고 확신하지만).

오픈 소스 기술 작가보다 훨씬 많은 오픈 소스 프로그래머가 있기 때문입니다.

문서를 최신 상태로 유지하려면 유지 보수 및 시간이 걸립니다. 문서가 부피가 클수록 더 많이 걸립니다. 그리고 코드와 동기화되지 않은 문서는 쓸모없는 것보다 나쁩니다. 공개하는 대신 오도하고 숨 깁니다.

잘 문서화 된 코드 기반은 덜 문서화 된 문서보다 낫지 만, 처음에 코드를 작성하는 한 문서를 작성하는 데 쉽게 걸릴 수 있습니다. 따라서 귀하의 질문은 잘 문서화 된 코드베이스 또는 두 배 큰 코드베이스를 갖는 것이 낫습니까? 코드가 변경 될 때마다 추가 개발자가 제공하거나 제공하지 않을 수있는 가치가있을 때마다 문서를 최신 상태로 유지하는 데 비용이 듭니까?

배송 코드가 이깁니다. 배송 코드 이외의 작업에 드는 노력을 줄이면 코드 배송이 더 자주 이루어질 수 있으며 리소스가 부족하기 전에 배송 될 가능성이 높습니다.

그렇다고 배송 이외의 일이 중요하다는 의미는 아닙니다. 문서화는 프로젝트에 가치를 더해 주며, 충분히 큰 프로젝트의 경우 다른 개발자를 추가하는 데 필요한 상호 연결 비용이 문서를 추가하는 것보다 훨씬 높을 수 있습니다. 언급 한 바와 같이 문서화는 프로젝트에 대한 투자를 증가시킬 수 있습니다 (새로운 프로그래머가 참여하기 쉽도록).

그러나 성공처럼 판매되는 것은 없습니다. 작동하지 않거나 흥미로운 것을 수행하는 프로젝트는 개발자를 끌어들이는 경우가 드 rare니다.

코드베이스의 문서는 메타 작업의 한 형태입니다. 많은 가치를 가지지 않는 코드 기반을 설명하는 멋진 문서를 작성하는 데 많은 시간을 할애하거나 코드 기반 소비자가 원하는 것을 만들고 코드 기반을 가치있게 만드는 데 시간을 할애 할 수 있습니다.

때때로 일을 더 힘들게하면 그 일을 더 잘하는 사람이됩니다. 프로젝트에 대한 헌신도가 높아지거나 (아키텍처를 학습하는 데 몇 시간이 걸리면 시간이 소요됨) 또는 기술 편견이 있습니다 (이미 관련 기술 전문가 인 경우 속도를 높이는 것이 더 빠를 것이므로 부족의 장벽) 이러한 문서의 중요성은 덜 중요합니다. 따라서 더 많은 전문가가 팀에 합류하고 초보자는 줄어 듭니다.

마지막으로 위에서 언급 한 이유로 현재 개발자는 코드 기반 전문가 일 가능성이 높습니다. 도움이되지 않는 등의 문서 작성 그들이 이미 지식을 가지고, 많은 코드베이스를 이해를, 그것은 단지 다른 개발자를하는 데 도움이됩니다. 대부분의 오픈 소스 개발은 개발자가 코드로 가지고있는 "가려운 곳을 긁는 것"을 기반으로합니다. 즉, 개발자가 아는 것이 거의 없다는 문서가 부족합니다.

추가 노력 외에도 일부 오픈 소스 프로젝트는 유지 보수 담당자를 위해 프리 랜싱 일자리를 얻기 위해 (문서를 구현하거나 교육을 받기 위해) 문서를 의도적으로 크롤링하고 있습니다. 코드 개요가 없을뿐만 아니라 API 및 자습서가 나쁘거나 많은 것들이 없습니다.

아주 인기있는 것의 이름을 말하면 : bluez. 근처의 장치를 스캔하는 다른 좋은 자습서를 찾는 것이 좋습니다.