코드 문서:전체 초보자 가이드
당신은 당신의 첫 번째 프로그래밍 작업에 약간의 방법이있어,일이 쉬워지고 있습니다. 처음에는 당신이 처리해야했던 모든 코드가 당신을 압도하고 혼란스럽게 할 수도 있지만,당신은 그것의 묘리를 터득하기 시작했습니다. 좋아요! 지금 당신은 당신이 다음 수준에 쓰는 부호를 가지고 가는 방법을 생각해 보고 있다. 프로그래밍 스택에 대해 배울 수있는 많은 것들이 있지만,그 중 많은 것들이 당신을 더 나은 프로그래머로 만들 것입니다.,당신이 일하는 스택에 상관없이 당신에게 봉사 할 몇 가지가 있습니다. 그 중 하나는 코드 문서입니다.
많은 개발자들은 값을 보지 못하거나 시간이 없다고 느끼기 때문에 충분한 문서를 작성하지 못합니다. 당신은 그 개발자 중 하나가 될 필요가 없습니다. 약간의 시간과 많은 연습으로,당신은 그것을 당신과 함께 오는 다른 사람 모두를 위해 사용하는 기쁨을 읽을 수 있도록 코드에 대한 문서를 추가 할 수 있습니다.
좋은 문서는 다양한 형태로 제공
대부분의 개발자가 코드 문서를 생각할 때 주석을 생각합니다. 주석은 코드에 중요한 추가 사항이 될 수 있지만 문서의 유일한 정의는 아닙니다. 설명서는 다른 사람이 어떻게 작동하는지 이해할 수 있도록 코드 외에도 작성하는 모든 것입니다. 이 방법으로 생각하지 않을 수도 있지만 코드 문서의 좋은 예는 추가 정보 파일입니다. 기본적인 문서의 좋은 보기는 급행 이다.추가 정보 파일. 그것은 프레임 워크에 대한 몇 가지 중요한 질문에 답하고 프로젝트에 포함 할 수있는 방법을 알려줍니다,그것을 설치하는 방법,및 테스트를 실행하는 방법.
좋은 문서 역시 문서 형태로 제공될 수 있다. 다시 한번 표현하십시오.제이는 좋은 예를 제공합니다. 이 버전의 문서는 프레임 워크를 사용하는 개발자를위한 참조 라이브러리에 가깝습니다. 개별 함수가 수행하는 작업과 해당 함수의 다른 매개 변수가 의미하는 바에 대한 질문에 대한 답변을 찾을 수 있습니다. 그 품질 문서 없이 익스프레스 그들 처럼 그것을 사용 하 여 거의 많은 팀 없을 것 이다.
물론 인라인 주석을 사용하여 코드를 문서화 할 수도 있습니다. 이러한 종류의 주석은 일반적으로 자신의 팀 외부의 사람들에게 코드에 대해 가르치는 데 사용되지 않습니다. 대신,그들은 당신의 동료 또는 미래의 자신에게 코드의 특정 비트에서 무슨 일이 일어나고 있는지 설명하는 데 유용합니다.
코드를 문서화해야하는 이유
위에서 언급했듯이 많은 개발자는 코드 문서의 목적을 이해하지 못합니다. 그들은 좋은 코드가 자체 문서화되어야하며 설명 할 필요가 없다고 주장 할 것입니다. 이 사람들은 한 마디로 잘못되었습니다. 진실은 좋은 문서는 모든 코드베이스의 필수적인 부분입니다. 왜? 왜냐하면 사람들은 그것이 무엇을하는지 이해하기 위해 모든 코드를 읽을 필요가 없기 때문입니다. 그 이전 문장의”사람들”은 미래의 자아를 포함하여 모든 사람을 지칭 할 수 있습니다.
진실은 종종 코드를 작성한 후에 코드를 이해해야하는”사람들”이 당신이라는 것입니다. 당신이 6 개월 전에 그것을 쓸 때 너무 영리한 듯 논리의 그 작은 비트는 오늘 이해하기 어려울 수 있습니다. 코드가 잘 문서화되어 있으면 코드가 수행하는 작업을 이해하는 데 시간을 할애 할 필요가 없습니다. 당신은 설명을보고 몇 초를 보내고 당신이 지금 작업하고있는 것을 다시 얻을 수 있습니다.
수십 또는 수백 명의 개발자가 사용하는 코드를 작업 할만큼 운이 좋다면 좋은 문서가 훨씬 더 중요합니다. 사용자의 생활은 크게 좋은 문서를 작성하는 데 소요되는 시간에 의해 개선 될 것입니다,그들은 그것을 당신을 감사합니다. 말 그대로!
기억해야 할 핵심은 좋은 문서를 작성하는 데 걸리는 시간보다 더 많은 시간을 절약 할 수 있다는 것입니다. 그것은 당신의 시간이 될 수도 있고,팀 구성원의 시간 일 수도 있고,결코 만날 수없는 사람들 일 수도 있습니다. 때로는 문서를 작성하는 것이 너무 복잡한 코드의 일부를 인식하여 단순화 할 수 있습니다.
몇 가지 일반적인 문서 실수
주니어 개발자로서 문서를 효과적으로 만드는 것을 배우는 데 시간을 할애해야합니다. 좋은 소식은 당신이 일반적인 실수를 피할 수 있도록 전에 갔던 사람들로부터 배울 수 있다는 것입니다.
언더 문서화
코드 문서에서 볼 수있는 일반적인 실수 중 하나는 이미 명확하게 보이는 정보를 문서화하는 것입니다. 예를 들어,게으른 개발자는 함수의 이름뿐만 아니라 각 매개 변수 및 개별 유형의 이름을 제공하는 블록을 추가하여 함수에”문서”를 추가합니다. 이 유형의 문서는 쓸모가 없습니다! 누군가가 함수의 이름과 매개 변수를 읽는 데 몇 초가 걸립니다. 그것은 문서가 아니라 단지 반복 일뿐입니다. 대신 설명서에는 함수가 수행하는 작업과 각 매개 변수가 함수의 동작을 변경하는 방법 또는 필요한 이유에 대한 빠른 정보가 포함되어야합니다.
오버 문서화
반대 패턴도 심각한 문제가 될 수 있습니다. 너무 적은 문서를 작성하지 않기 위해 일부 개발자는 함수에 포함 된 모든 작은 논리에 대한 설명을 작성하는 것을 좋아합니다. 그들은 꼼꼼하게 기능을 만드는 들어간 모든 근거를 문서화. 그들이 완료 될 때까지,그들은 문서를 작성했던 것처럼 함수를 작성하는 데 오래 소비했을 것입니다. 더 나쁜 것은,문서는 종종 이해하기 어렵고 코드를 읽는 것만 큼 오래 걸립니다. 그런 종류의 문서는 또한 시간 낭비입니다. 대신,좋은 문서는 무엇을 왜 모두에 대한 기본적인 설명을 제공합니다. 코드의 특히 까다로운 부분이 있다면 설명서는 그 부분 만 설명해야합니다.
을 문서화하기 위해 테스트에 의존 할 때 때때로 최상의 문서 형식이 단위 테스트라고 주장하는 사람을 가로 질러 실행됩니다. 단위 테스트를 읽는 것은 종종 코드 자체를 읽는 것만 큼 어렵습니다. 코드가 무엇을 배우기를 원하는 개발자는 모든 단위 테스트를 읽고 읽는 동안 큰 첫 걸음을 내딛을 것입니다. 많은 것은 하기 위하여 착수하는 무슨을 달성하기 전에 다만 포기할 것이다. 단위 테스트는 모든 코드베이스에 귀중한 추가 사항이지만 좋은 문서를 대체하지는 않습니다.
다음 단계로 문서를 가져 오는 방법
큰 코드베이스에서 작업하는 경우,코드 문서는 위협적 일 수 있습니다. 그것은 당신이 바다를 끓이려고하는 것처럼 느낄 수 있습니다. 큰 코드 베이스가 있거나 좋은 문서가 중요하다는 것을 알고있는 경우 자동화 된 코드 문서화 도구를 조사 할 수 있습니다. 이러한 도구는 전체 팀을 위해 일관되고 좋은 문서를 작성하는 프로세스를 대폭 단순화합니다. 고스트 독과 같은 도구는 지능적으로 코드를보고 키 누름의 부부와 함께 문서를 킥 시작하는 팀에 의해 설립 된 템플릿을 사용합니다. 자동화 된 문서 도구는 문서 작성을 반대하는 다른 일반적인 이유 중 하나를 제거:그것은 너무 많은 시간이 걸립니다.
일관된 문서가 있으면 다른 도구를 사용하여 해당 문서를 쉽게 공유할 수 있습니다. 자동화 된 문서 도구는 코드가 제공하는 공개 문서와 같은 좋은 문서를 개발하는 데 어려움을 겪습니다.
오늘 시작하기
훌륭한 문서 작성은 코드를 작성하는 것보다 훨씬 쉽습니다. 코드와는 달리,문서는 모두 또는 아무것도 기업이 아니다. 매일 하나의 기능에 대한 좋은 문서를 작성하는 목표로 시작합니다. 그런 종류의 연습은 건강한 습관을 구축하고 코드베이스의 일부를 이해하려고 노력하는 데 훨씬 적은 시간을 할애 할 때 도로의 보수를 볼 수 있습니다. 시간이 지남에 따라 좋은 문서가없는 코드를 작성할 때 잘못된 느낌이 들기 시작할 것입니다. 코드 검토 중에 동료에게 문서를 개선하는 방법을 지적하기 시작합니다. 하나의 작은 습관은 전체 비즈니스에 대한 팀의 코드를 향상시킬 것입니다.
저자에 관하여
에릭 보어 스마
에릭 보어 스마
에릭 보어 스마
그는 길을 따라 배운 것들에 대해 이야기하는 것을 좋아하고 다른 사람들에게도 듣고 배우는 것을 즐깁니다.
