Writing code documentation can be overwhelming when there’s no smooth process in place. Streamlining best practices and setting automation in your favor works a long way toward getting permanently up-to-date content that reflects the important pieces of your codebase.
원활한 프로세스가 없을 경우 코드 문서 작성이 부담스러울 수 있습니다. 모범 사례를 간소화하고 자동화를 사용자에게 유리하게 설정하는 것은 코드 기반의 중요한 부분을 반영하는 영구적인 최신 콘텐츠를 얻는 데 큰 도움이 됩니다.
요약 :)
시간을 할당하는 것부터 최신 상태로 유지하는 것까지 소프트웨어 문서와 관련된 모든 것이 까다롭습니다.
성공적인 문서화는 달성하기 까다로우며 영향을 측정할 시간이 충분하지 않은 경우가 많습니다. 최종 사용자 경험에 실질적인 영향을 미치지 않기 때문입니다.
우리는 훌륭한 문서에 가치를 부여할 능력이 없습니다. 그 때문에 즐거운 문서를 작성하고 유지하려는 노력이 시간 투자와 적절한 계획을 초과하는 경우가 드뭅니다.
시간을 할당하는 것부터 최신 상태로 유지하는 것까지 소프트웨어 문서와 관련된 모든 것이 까다롭습니다. 성공적인 문서화는 달성하기 까다로우며 영향을 측정할 시간이 충분하지 않은 경우가 많습니다. 최종 사용자 경험에 실질적인 영향을 미치지 않기 때문입니다. 우리는 훌륭한 문서에 가치를 부여할 능력이 없습니다. 그 때문에 즐거운 문서를 작성하고 유지하려는 노력이 시간 투자와 적절한 계획을 초과하는 경우가 드뭅니다.
페니 또는 다임 #
소프트웨어 개발자는 코드와 콘텐츠를 작성하는 사업에 종사하고 있습니다(음, 우리 대부분은 ????). 우리가 제공하는 기능과 이를 통해 들어오는 수익에 대해 벤치마킹했을 때 급여를 쉽게 정당화할 수 있습니다. 따라서 동료들이 코드와 상호 작용할 수 있도록 이러한 기능에 대해 작성하고 교육할 때 우리는 종종 다음 기능을 제공하거나 불쾌한 버그를 수정하는 것과 반대되는 시간의 가치에 대해 의문을 제기합니다. 기술 부채가 너무 많은데 리팩토링이 필요한 코드에 대해 작성하는 이유는 무엇입니까?
우리는 그 시간을 즉시 저장합니다. 이는 분명한 선택입니다. 바로 코드로 돌아갑니다. 그리고 우리는 약간의 시간을 절약했습니다. 조금 빨리 감기; 동료가 여기에 뛰어들어 변경 사항을 구현해야 합니다. 당신은 외출 중이고(다음 큰 일을 위해 일하거나, 회의 중이거나, 휴가 중이거나, 회사를 그만둘 수도 있습니다!) 문서가 없습니다. 그 동전들은 이제 이자가 쌓이기 시작합니다. 다행히도 코드에 몇 가지 주석이 있습니다. src실제로 를 의미 source하고 function sort(a, b)두 개의 정수를 취 한다는 것을 아는 것이 좋습니다 . 그러나 추론은 실제로 존재하지 않으므로 계속 파헤쳐 봅시다. 풀 요청에는 설명이 없습니다.git blame코드를 작성한 사람이 주변에 없기 때문에 도움이 되지 않습니다. 탐정과 리버스 엔지니어링을 할 때인 것 같습니다. 그 페니는 이제 다임입니다. 설명하는 것은 조사하는 것보다 인지 과부하가 훨씬 적습니다. 따라서 우리 앱을 개발하는 비용은 작업별로 개발자 시간이 증가함에 따라 증가하고 있습니다.
문서화는 위생 작업입니다. 우리는 물건을 깔끔하고 편안하며 인체공학적으로 유지하기 위해 노력합니다. 좋든 나쁘든 개발자 경험의 직접적인 촉매제입니다. 그리고 개발자 경험은 개발자가 잡초를 헤쳐나가는 대신 정말 중요한 코드에 얼마나 집중할 수 있는지를 결정합니다.
양치질 #
바라건대, 우리 모두 양치질이 매일 해야 하는 중요한 일이라는 데 동의할 수 있기를 바랍니다. 금요일에 모든 일을 하고 건너뛴 날을 보충할 수 있는 습관이 아닙니다. 이 경우 문서화도 비슷합니다. 물론 분기 말까지 모두 작성할 수 있지만 훨씬 더 어렵고 시간이 많이 소요될 것입니다. 예를 들어: 3개월 전에 무엇을(또는 왜!) 코딩했는지 기억하십니까?
문서화의 인지적 과부하는 코드를 배송할 때부터 커집니다. 이상적으로 문서화는 테스트 작성(우리 모두가 하는 일입니다!)과 같으며 무언가를 변경할 때마다 문서를 업데이트합니다.
장애물 제거 #
불행하게도 우리 대부분은 문서 작성 습관을 만드는 데 실패합니다. 이는 워크플로우가 종종 마찰로 가득 차 있기 때문입니다. 코드를 완료하고 파일(또는 IDE 또는 프로젝트)을 닫고 Markdown 편집기(또는 Jira 또는 Wiki 등)로 이동합니다. 이제 지식을 넣을 올바른 위치를 찾아야 합니다. 방금 만들었으면 검토를 위해 제출하세요. 다른 사람들은 우리가 가장 좋은 부분을 선택했는지, 충분히 명확하게 작성했는지 등을 알려줄 것입니다. 한편, 코드는 기다릴 수 없습니다. 사용자는 이미 반짝이는 새 기능을 받고 있습니다. ( 그게 너라면, 힘들어! 거기 있었어, 해냈어. 너는 내 동정심을 가지고 있어. )
프로세스가 진행됨에 따라 결정에 의문이 제기됩니다. 그렇습니다. 연습을 하면 완벽해집니다. 하지만 이상적으로는 실사를 실행하기 위해 그렇게 많은 시간(및 에너지!)을 소비할 필요가 없습니다. 이 마찰은 습관을 유지하는 데 불리하게 작용하고 있으며 코드를 넣을 위치를 찾는 데 소비한 시간은 우리의 동기를 고갈시켰습니다.
움직이는 조각을 연결 #
평소와 같이 마찰 문제에 대한 개발자의 솔루션은 자동화 입니다. 지루하고 반복적인 작업을 파생물로 만들어 피하십시오. Swimm 은 "문서 생태계"(매우 적절한 이름)라고 부르는 많은 결정 중 몇 가지를 수행함으로써 이를 수행합니다.
문서를 어디에 둘까요? 바로 거기에 코드가 있습니다.
언제 문서를 작성합니까? 당신이 그것을 구현함에 따라. 또는 PR을 열 때(최소!).
요약하면 방법을 작성합니다. 바로 그 자리에서 방법을 설명합니다. "마법 같은" 부분은 배치되어 있기 때문에 코드의 매개변수와 변수를 문서 의 텍스트에 직접 문서화할 수 있을 때 나타납니다. 이렇게 하면 코드가 변경될 때 문서가 이제 구식임을 인식하고 전체 팀에 이에 대해 플래그를 지정할 수 있습니다.
이 모든 깔끔한 자동화에는 약간의 설정과 코딩 인터페이스 및 관련 프로세스에 대한 약간의 변경이 필요합니다.
문서에 코드 #
VS Code 또는 JetBrains의 IDE 중 하나를 사용하는 경우 확장/플러그인을 통합할 수 있습니다. 코드를 작성하면 이미 문서화된 코드 옆에 "Swimm 웨이브"가 표시되므로 링크를 따라 향상된 Markdown 편집기에서 코드를 편집할 수 있습니다. 이 편집기에는 코드에서 검사되는 몇 가지 흥미로운 자동 완성 기능이 있습니다(변수 이름을 입력하기 시작하면 자동 완성되는 것을 볼 수 있습니다). 코드를 문서에 연결하는 메커니즘이므로 가능한 한 많이 사용하십시오.
문서로 버전 관리 #
GitHub를 사용하면 문서가 코드와 결합되면 동일한 PR에서 검토도 수행됩니다. 통합 봇은 변경된 코드 전체에서 스마트 토큰 을 식별할 수 있으며 이미 적용된 조정(바로 그 자리에서 검토하라는 메시지 표시) 또는 변경되지 않은 항목(또한 검토 메시지 표시)에 플래그를 지정할 수 있습니다. PR 프롬프트처럼 보이는 개별 댓글을 통해 PR 검토자는 각 댓글 섹션을 얼마나 편안하게 사용하는지에 따라 하나씩 승인할 수 있습니다.
GitHub의 Swimm PR 리뷰
또한 자동 확인(Swimm의 특허받은 자동 동기화)을 사용하면 자동 승인 및 알림 트리거를 설정하거나 완전히 음소거할 수도 있습니다. 따라서 팀은 알림 과부하를 피하고 가장 적합한 방식으로 변경 사항을 인식하는 방법을 조정할 수 있습니다.
