우리는 지금 프로그래머를위한 문서화에 대해 많은 이야기를하고 있습니다. 이 부분을 어떻게 처리합니까?PHP가있는 크고 작은 프로젝트 용 문서?
"대규모"PHP 프로젝트에 새로운 팀원을 소개하는 가장 좋은 방법은 무엇입니까? 새로운 사람은 무엇을 필요로합니까?
내 생각이 지금까지 :
어떤 종류의 생성 .. 인프라에 대한 정보 (데이터베이스, 방화벽 ..)
프로젝트를 다른 사람에게 양도해야하는 경우 (PHP처럼 좋지 않을 수도 있음) 다른 것을 제공하십시오.
"서버 데이터를 읽는 기능을 추가하려면" 모델 xYZ에 넣으시겠습니까? "
영어가 나쁘면 죄송합니다. :)
세 가지 모두를 사용해야합니다.
그러나 문서를 복잡하게 만들지 마세요. 최신 상태로 유지하는 것이 어려울수록 유지 관리가 어려울 수 있습니다. IMHO, 새로운 프로그래머에게 코드베이스를 소개하는 최소한의 코딩 가이드 라인 (변수를 호출하는 방법, 클래스를 호출하는 방법, 헝가리 표기법을 사용하고 있습니까?) 및 phpdoc입니다. 코드에서 타사 라이브러리와 대형 구성 파일을 많이 사용하는 경우 코드가 작고 새로운 시스템에서 작동하도록하는 단계를 설명하는 작은 PDF 파일을 작성하십시오.
단위 테스트를 사용하는 경우 해당 테스트를 문서화해야합니다.
코드베이스를 포기한 후에는 새로운 코더로 자주 전화 할 것을 기대하십시오. 당신이 논리적이고 명확하게 보이는 것은 새로운 사람이 아닌 것 같습니다.
프로젝트에 API가있는 경우 다른 샘플 이외에도 샘플 사용법, 예제 등을 제공 할 것입니다.
설명서가 좋지만 가이드로 생각하십시오. 프로그래밍을 가르치기 위해 쓰여서는 안되며 쉽게 구식 인 문서가되어서는 안됩니다.
새로운 프로젝트에 참여할 때마다 일관되게 필요한 것은 코드의 위치와 액세스 방법을 파악하는 것입니다. 코드 라인을 작동하는 개발 또는 스테이징 환경에 맞추면 이전 개발자의 "패턴"을 실험하고 발견하는 데 신속하게 문이 열립니다.
인터페이스에서 작은 조정을 할 수 있다면 너트를 부숴 먹었을 때 데이터를 향해 뒤로 움직일 수 있습니다.
그렇지만 문서가 거의 없거나 거의없는 게시판 프로젝트에 익숙해졌습니다. 모두가 그걸로 편안하지 않습니다.
다른 프로그래머의 저작물의 거의 전부 인 중형 코드베이스를위한 코드입니다 (저는 새로운 사람입니다).우리는 API phpdoc 주석과 버전 관리 우수 사례 텍스트 파일로부터 자동으로 문서화 된 문서를 가지고 있습니다. 더 포괄적 인 인라인 주석과 자동화 된 테스트와 같은 두 가지 목적을 포기할 것입니다.
일반적으로 새로운 기능을 빌드하는 데 좋은 api 문서가 있지만 인라인 코멘트로는 잘 설명되는 버그를 찾아내는 데 특히 유용하지 않습니다.
그래서 저는 코드 라인을 터치하기 전에 새로운 코드의 동작을 주석에 배치하려고합니다. 나는 Test Driven Design으로 옮기고 싶지만, 아직 그 시점에 도달하지는 못했다.
그래, 필자는 유능한 코더 다.하지만 코드베이스의 크기와 복잡성, 코드의 대부분이 다른 사람에 의해 만들어 졌다는 것을 의미한다. 나는 코드베이스의 잠재적 소스에 대한 설명을 위해 자주 그에게 가야만한다는 것을 의미한다. 버그. 따라서 코드베이스를 계속 옮겨 놓은 상태에서 코드베이스를 만드는 데 정말로 투자한다면 가능한 한 리소스로 활용할 수있는 방법을 고려하십시오.
나는 중요한 고려 마지막 한가지는 git
(또는 수은, 또는 다른 D.V.C.S.)는 documentative에 대한 역사를 저지하고 그들과 함께 올 수있는 코드로 potential web-interface.