신청서를 어떻게 문서화합니까?

Question

다른 개발자가 쉽게 사용하고 유지 관리 할 수있는 방법으로 시스템을 문서화하는 방법을 알지 못합니다. 소스 코드를 문서화하는 것이 좋고 필수적이지만, 응용 프로그램 자체에 대한 개요를 제공하는 것으로 충분하지 않다고 생각합니다.

Java는 특정 클래스의 기본 사용법 만 설명한 소스 코드에 대부분의 문서를 보관하고있는 것으로 보입니다. DecimalFormat 쉼표를 소수 구분 기호로 사용하는 객체를 만드는 것은 일반적으로 자세한 내용은 API 설명서를 참조하십시오. (해당 설명서에서 이해할 수있는 한 DecimalFormatSymbols 및 Locale 클래스가 포함되어 있지만 요점은 다음과 같습니다. 추가 정보 없이는 확실하게 알 수 없습니다). 누락 된 부분은 별도의 Java tutorials으로 처리하려고 시도합니다. 대부분이 라이브러리의 특수한 특수 용도를 설명합니다.

Ogre3d 그래픽 엔진은 응용 프로그램의 일반적인 설명을위한 특별한 페이지를 만들었습니다.이 페이지는 ogre manual으로 제공되며 엔진의 전체 내용을 설명하려고 시도합니다.

나는 도서관의 범위가 여기 같지 않다는 것을 알고있다. 나는 자바를 강타하는 것이 아니라 문서화 철학의 적절한 비교라고 생각했다.

최근 우리 회사의 모든 소스 코드를 우리 회사의 소스 코드에 넣기 시작했습니다. 다른 사람들이 어떻게 자신의 응용 프로그램을 문서화하고 어떻게 작동시키는 지 (또는 더 많은 수입이 프로젝트의 다른 개발자에게) ? 프로젝트가 특정 (코드 -/팀 -) 크기 이상으로 증가하면 다른 개발자가 참여하는 것이 어려워지고 :

편집

는 내가 조금 명확히해야 할 것 같아요. 나는 코드 문서가 코드를 이해하는 데 매우 중요하다는 것을 알고 있지만 프로젝트 작업을 시작하는 것으로는 충분하지 않다고 생각합니다. 다른 사람이 그에게 자습서 (왜 일들이 그들이하는 것처럼 보이는지를 설명하는 것)를 주거나 어딘가에 문서화 할 필요가 있습니다.

실제 질문은 다음과 같습니다. 새로운 개발자에게 제공하는 문서와 그 문서가 얼마나 유용합니까? 그들은 200 페이지 시스템 설명서를 읽나요? 그들은 코드에 먼저 뛰어 들었습니까? 그들이 그것을 읽은 후 얼마나 많은 종류의 질문을합니까?

나는 동료의 반응 이후가 아니라 문서 프로세스의 효율성 (반응을 지표로 언급 함)입니다.

Answer 1

처음에는 분명하지만 많은 사람들이 그것을 잘 따르지 않는 것처럼 보입니다. self-documenting code.

두 번째로 refactor는 읽기 쉬운 코드입니다.이 고전적인 예는 Extract Method refactoring입니다.

세 번째로 이것은 명백한 것처럼 보입니다. JavaDoc 스타일의 주석을 쓰면 외출하지 마십시오. 이전 회사의 동료 중 한 사람이 다른 사람의 코드를 꼼꼼히 훑어 보았습니다. 문서는 코드의 기능과 정반대였습니다. 코드를 많이 문서화하려면 코드에 "생존"하는 것이 중요합니다.

너무 자주 사람들이 코드를 문서화하고 변경 한 다음 문서를 업데이트하지 않습니다. 나쁘게 문서화 된. NET 코드를 우연히 발견하면 일반적으로 Reflector을 사용하여 무슨 일이 일어나는지 더 잘 이해할 수 있습니다.

마지막으로 사람들은 단위 테스트가 문서로 작동 할 수도 있음을 잊어 버립니다.

Answer 2

문서를 소스 코드에 보관하려고합니다. C#에서 일하기 때문에 /// 시스템을 사용하여 문서화합니다. 나중에 SandCastle을 사용하여 설명에서 문서를 생성 할 수 있습니다. 나는 위키가 높은 수준의 문서화를위한 좋은 아이디어라고 생각한다.

Answer 3

우리는 코드 안에 문서를 유지하려고 노력합니다. 우리는 Javadoc을 사용합니다.

Doxygen은 소스 코드에서 직접 클래스 다이어그램을 생성하는 좋은 도구입니다.

우리가 사용하는 플랫폼에 따라 때때로 역 공학을 통해 ER 다이어그램을 생성합니다. 이렇게하기위한 도구가 많이 있습니다.

이것은 클라이언트가 얻을 문서입니다.

설치 절차, 시스템 백업 방법, 새 배포 방법 등 은 위키 시스템에 문서화되어 있습니다.

Answer 4

JamesC78에 동의해야합니다. 내가 자바에서 프로그래밍 할 때, 나는 개발자들에게 일반적인 주석과 JavaDocs를 사용한다. 그런 다음 위키에 프로그램을 실행하는 방법, 찾을 대상, 사용중인 데이터베이스 테이블, 수행중인 작업 등 하위 수준의 설명서를 업데이트합니다.

Answer 5

나는 3과 같은 질문을 읽고 다시 읽습니다. 귀하의 제품 사용에 대한 문서 작성 대 제품 개발 방법에 대한 문서 작성과 최종적으로, 나는 아직도 귀하가 어떤 사람인지를 알지 못합니다! ;)

나는 이제 나 자신을 위해 일하기 때문에, 나는 그것에 대해 꽤 끔찍하다는 것을 인정해야한다. 나는 나의 청중 (나)에 대해 주로 나에게 알리미 또는 설명의 형태로 언급한다. 나는 때때로 약간 끔찍한 기억을 가지고 있기 때문에 이것은 유용한 운동이다. 얼마나 많은 다른 사람들이 내 문서에서 얻을지 모르겠지만 그것은 나를 위해 작동합니다. Visual Studio (///)에 내장 된 도구를 사용하여 나중에 javadoc 또는 산소와 유사한 자동 문서를 만들 수 있습니다. 또한 // TODO를 많이 사용합니다.

마찬가지로 제품을 사용하는 방법을 문서화하는 방법은 간단합니다. 나는 개발자가 개발자로서 제품 사용을 문서화해서는 안되며 최종 사용자보다 훨씬 다른 방식으로 제품을 사용할 것이라고 단호하게 믿습니다. 필자의 마지막 일은 문서화가 일반적으로 회사 내의 고급 사용자 또는 품질 보증 담당자에게 전달되었으므로 그 사람이 개발팀에 대한 액세스 권한을 갖고 있으면 질문이 생길 수 있습니다. 비어있는 점은, 물론 대부분의 개발자는 기술적 인 사용자가 아닌 사람들과 의사 소통을 잘하지 못합니다. 물론 예외가 있습니다.

그렇지 않으면, 일을하는 방법이 나옵니다. 매뉴얼이 있습니다. 일이 느린 경우 몇 달마다 업데이트 할 것입니다. 제 경우에는 그것은 거대한 단일 노트 문서였습니다. 그러나 내가 상처를 입었고 잠시 쉬었을 때, 그것은 내가받은 전화의 수를 헤아릴 수없고 최소화 시켰습니다. 이후로, 나는 모든 개발자들에게 다양한 수준의 성공을 거두어 유사한 저널을 보관하게했습니다. 즉, 이것은 직업 안정에 직접적으로 영향을 미치므로 자신의 입장에서 안전하게 느끼기를 바랍니다.

Answer 6

이것이 파이썬 프로젝트라면 나는 doctest을 제안 할 것입니다.

예를 들어 간단한 자문 파일 잠금 패키지를 사용하는 방법을 설명하는 small doctest은 다음과 같습니다.

이 자바에 대한 두 개 이상의 doctest가 같은 시스템은 다음과 같습니다 JDoctest 및 doctestj