소개 좋은 문서는 유지 관리 가능한 소프트웨어 프로젝트에 매우 중요합니다. 새로운 엔지니어 온보딩을 용이하게 하고 지속적인 기여를 더 쉽게 만듭니다. 문서가 부실한 프로젝트는 장기적으로 계속해서 유지, 개선 및 반복하기가 점점 더 어려워질 수밖에 없습니다. 소프트웨어 개발 수명 주기는 연속적입니다. 유지 관리 가능성은 주어진 프로젝트에 대해 시간 경과에 따른 변화가 얼마나 지속 가능한지를 측정한 것입니다. 문서화는 그 이야기에서 작지만 중요한 부분입니다. 추가 고려 사항은 유지 관리 가 중요한 이유에 대한 지속적인 시리즈를 참조하십시오 . 문서에 대해 생각하는 방법 좋은 문서 작성은 엔지니어가 문서화 시기와 대상, 올바른 정보를 캡처하고 전달하는 방법에 대해 올바른 결정을 내릴 수 있도록 하는 사고방식에서 시작됩니다. 문서는 사람을 위한 것입니다. 모든 좋은 글은 청중을 인식합니다. 문서는 일반적으로 사용자 문서와 개발자 문서의 두 가지 범주 중 하나로 분류됩니다. 사용자를 위한 작성은 다음과 같아야 합니다. 접근 가능 - 친근한 어조를 사용하고 탐색 및 이해하기 쉽습니다. 철저 - 정보를 생략하지 않고 세부 사항과 설명에 관대합니다. 연결됨 - 스마트해야 하고 페이지는 상황에 따라 연결되어야 하며 사용자를 다음 논리적으로 안내하는 데 도움이 되어야 합니다. 엔지니어를 위한 글쓰기는 다음과 같아야 합니다. 솔직함 - 불필요한 정보를 생략하고, 직접적이고 구체적이며, 드물지만 부족하지 않습니다. 기술 - 도메인별 언어를 사용하고 현학적이며 필요한 경우 관련 리소스로 연결됩니다. 조직화 - 구조화되고 탐색하기 쉽습니다. 이 기사의 나머지 부분은 Viget 이 일반적으로 참여하는 소프트웨어 프로젝트 유형에 대한 주요 관심사인 개발자 문서에 중점을 둡니다 . 문서로 간주되는 것 소프트웨어 프로젝트의 문서에는 다음을 비롯한 다양한 항목이 포함됩니다. README.mds와 CONTRIBUTING.mds 코드 주석 자동화된 테스트 풀 리퀘스트 설명 새로운 기능 또는 버그 보고서에 대한 문제 설명 풀 리퀘스트 및 발행 템플릿 커밋 메시지 코드 리뷰 지원 도메인 또는 프로세스별 문서 이들 각각은 프로젝트의 유지 관리 가능성을 형성할 미래 엔지니어를 위해 신중하게 고려되어야 합니다. 문서화해야 할 사항 프로젝트 전제 조건 및 소프트웨어 요구 사항 프로젝트의 패키지 관리자가 관리하는 종속성이 아닌 시스템에 설치해야 하는 모든 필수 프로그램의 전체 목록 로컬 개발 설정 지침 단계별로 프로젝트를 시작하고 실행하기 위해 수행할 작업. 여기에 복사+붙여넣기 가능한 명령과 스니펫을 포함하는 것이 좋습니다. 비밀 및 필수 자격 증명을 찾을 수 있는 위치 버전 제어에 체크인되지 않았지만 애플리케이션을 실행하는 데 필요한 모든 민감한 정보. 암호 또는 암호를 가져오기 위해 실행할 명령에 대한 직접 링크가 있는 경우 여기에서 해당 정보를 캡처할 수 있습니다. 배포: 작업 프로세스, 배포 방법, 원격 환경에 대한 정보 이것은 변경 사항을 원격 환경으로 푸시해야 하는 새로운 기여자에게 특히 중요합니다. 기여 가이드라인 코드 스타일, 린팅/포맷팅, 커밋 스타일, 좋은 이슈와 풀 리퀘스트 생성 단계, 외부 문서, 행동 강령, 기타 프로젝트 프로세스에 대한 정보. CONTRIBUTING.md이들에게 좋은 곳입니다. 까다롭거나, 이상하거나, 예상치 못한 코드 지금부터 1년 후 다른 기여자나 자신에게도 이해하기 쉽지 않을 수 있는 코드를 작성해야 하는 타당한 이유가 있습니다. 이러한 영역은 존재 이유를 설명하는 자세한 코드 주석 또는 커밋 메시지에 적합합니다. 테스트 방법론 기여자가 적절하게 테스트된 코드를 작성하고 유지하는 데 도움이 되는 기대치, 적용 범위 임계값, 테스트 격리, 모의, 고정 장치, 시드 및 기타 항목에 대한 참고 사항입니다. 복잡한 애플리케이션 동작 이 정보를 표현하는 가장 좋은 방법 중 하나는 테스트 형식입니다. 미래의 기고자들은 유효한 프로그램 상태와 유효하지 않은 프로그램 상태와 그 상태에 들어가는(또는 방지하는) 방법에 대한 주장을 하는 것에 감사할 것입니다. 기술 부채 기술 부채 에 대한 생각과 기대치를 정리하는 것이 유용할 수 있습니다. 추적 방법(예: 기술적 부채와 관련된 좋은 코드 주석 작성 방법, 향후 리팩토링 문제 생성 여부)? 언제, 어떻게 상환할 예정입니까(예: 기술 부채 잔고를 처리하기 위해 시간을 할당하기 위한 프로젝트/팀 프로세스)? 이 목록이 완전하지는 않지만 어떤 종류의 항목을 신중하게 고려할 가치가 있는지 고려할 때 좋은 출발점이 되어야 합니다. 유지 관리 가능한 문서 작성 다음은 시간이 지남에 따라 더 쉽게 기여할 수 있도록 프로젝트 문서를 반복할 때 염두에 두어야 할 몇 가지 사항입니다. 문서는 다음과 같아야 합니다. 편집 가능 - 추가 또는 수정하기 쉬움 문서 구조를 최대한 단순하게 유지하면 정보를 추가하거나 변경할 위치를 쉽게 알 수 있습니다. 정보를 계층적으로 구성하고 명확한 제목을 사용합니다. 찾기 가능 - 주어진 작업에 대한 관련 정보를 쉽게 찾을 수 있습니다. 문서를 프로젝트의 관련 부분과 함께 배치하면 어디를 봐야 하는지 쉽게 알 수 있습니다. 모든 것을 한 곳에 두지 마십시오. 가능한 관련 프로젝트 범위에 가까운 여러 파일을 선호합니다. 제거 가능 - 더 이상 관련 이 없을 때 쉽게 제거할 수 있습니다. 이전 요점을 유지하면서 함께 배치된 문서는 기능을 삭제할 때 더 쉽게 제거됩니다. 일반적으로 삭제된 특정 코드나 기능과 관련된 파일 부분을 다른 곳에서 찾는 것을 기억하기가 더 어렵습니다. 유지 - 최신 상태로 유지 순환 논리는 제쳐두고 시간이 지남에 따라 문서를 선별해야 합니다. 즉, 작업 추정 및 계획에서 업데이트하는 데 걸리는 시간을 고려하고, 코드 검토에서 문서가 올바르게 업데이트되었는지 확인하고, 정확성을 보장하기 위해 정기적으로 문서를 감사해야 합니다. Markdown으로 작성되고 버전 관리에 체크인된 문서를 통해 쉽게 편집하고 검색할 수 있습니다. 명심하십시오… 코드 주석은 코드 엔지니어가 코드 작업을 하는 동안 주석을 읽는 데 시간과 주의를 기울이는 것입니다. 코드 주석에서 전달되는 불필요한 정보의 양을 최소화하기 위해 노력해야 합니다. 불필요한 주석은 중요한 주석의 영향을 분산시키고 희석시킬 수 있습니다. 좋은 코드는 좋은 문서화로 이어집니다. 코드가 자체 문서화되고 추가 정보를 전달할 필요가 없을 때 훌륭하지만 때로는 새로운 기여자에게 명확하지 않을 수 있는 특정 접근 방식을 필요로 하는 요구 사항이 있습니다. 이러한 경우 특정 전략이나 결정 뒤에 있는 "이유"를 문서화하는 설명을 추가하는 것이 유용합니다. 오래된 문서는 문서가 전혀 없는 것보다 나쁠 수 있습니다. 엔지니어가 문서를 읽고 구문 분석하는 데 시간과 노력이 필요합니다. 해당 정보가 잘못된 경우 혼동을 줄 수 있으며 수행할 작업을 결정하는 데 추가 주기가 소요될 수 있습니다. 코드를 업데이트해야 하나요 아니면 문서를 업데이트해야 하나요? 모든 문서가 코드에 관한 것은 아닙니다 . 프로젝트의 지원 측면을 문서화하는 것이 중요합니다. 예: 오류 모니터링 프로세스/절차, 제품 소유권 및 의사 결정, 버그 추적 및 문제 관리, 품질 보증 정보. 문서화는 새로운 기여자가 시작하기에 좋은 장소입니다. 새로운 기여자는 프로젝트 문서의 유지 관리 가능성에 기여할 수 있는 좋은 위치에 있습니다. 초기에 로컬에서 프로젝트를 설정하는 동안 설정 지침, 프로젝트 요구 사항, 기여 지침 및 필수 자격 증명을 감사하는 것이 편리합니다. 정확하지 않거나, 오래되었거나, 누락된 정보를 접했을 때 이 문서의 편집에 기여하는 것은 증가하는 동안 피칭할 수 있는 좋은 방법입니다. 언어 및 도구 지원 바퀴를 재발명하지 마십시오. 사용하는 언어에 관계없이 코드를 문서화하기 위한 규칙과 표준 접근 방식을 활용하십시오. 시간이 지남에 따라 활용해야 하는 일반적인 모범 사례 집합을 추출한 광범위한 엔지니어 커뮤니티가 있을 수 있습니다. 모든 언어가 동일한 것은 아니며 일부는 문서를 최우선 관심사로 취급합니다. 언어별 도구와 관용구를 사용하여 작업을 문서화합니다. 가능할 때마다 표준 도구 사용 자동화된 도구를 사용하여 액세스 가능한 문서를 유지 관리하면 시간을 절약할 수 있고 언어별 도구를 사용하여 접근 방식을 표준화할 수 있으며 관용적 접근 방식을 사용하면 문서를 보다 원활하게 유지 관리하고 업데이트할 수 있습니다. 외침: 비약 José Valim 은 Elixir 에서 @moduledoc및 @doc. 코드 주석에는 실행 가능한 예제 코드가 포함될 수 있습니다. Elixir 빌드 도구인 Mixmix docs 는 . DocTest 를 사용하면 테스트 모음에서 코드 예제를 실행할 수 있으므로 오래된 것이 유효하지 않은지 확인할 수 있습니다. 문서 작성 의 Elixir 페이지 는 흥미로운 차이점을 보여줍니다. "문서는 귀하와 API(응용 프로그래밍 인터페이스) 사용자 간의 명시적 계약입니다. 제3자 개발자, 동료 또는 미래의 자신입니다. 모듈과 함수는 API의 일부인 경우 항상 문서화해야 합니다. 코드 주석은 코드를 읽는 개발자를 대상으로 합니다.” 다음은 실제로 어떻게 보이는지에 대한 예입니다. 주어진 Elixir 모듈 에 대해 선택적으로 예제 호출 및 관련 출력을 포함하여 모듈과 각 기능에 개별적으로 주석을 달 수 있습니다. defmodule GameApp.Game do @moduledoc """ `GameApp.Game` defines a struct that encapsulates game state as well as many functions that advance the game state based on actions that players can take. """ # ... module attributes, typedefs, imports, aliases and struct info omitted for brevity ... @doc """ Creates a game. ## Examples iex> Game.create(shortcode: "ABCD", creator: Player.create(id: "1", name: "Gamer")) %Game{ shortcode: "ABCD", creator: %Player{id: "1", name: "Gamer"}, players: %{"1" => %Player{id: "1", name: "Gamer"}}, scores: %{"1" => 0}, funmaster: %Player{id: "1", name: "Gamer"}, funmaster_order: ["1"] } """ @spec create(keyword()) :: Game.t() def create(attrs \\ []) do struct(Game, Enum.into(attrs, %{config: %GameConfig{}})) |> player_join(Keyword.get(attrs, :creator)) end 를 실행 mix docs하면 생성된 파일, 일부 글꼴, 스타일 및 JavaScript 가 포함된 docs폴더 가 생성됩니다. .html그런 다음 이러한 파일을 어디에서나 호스팅하고 앱의 주석에서 완전히 생성된 문서 사이트 를 탐색할 수 있습니다. 위의 코드 샘플에 대한 문서는 여기에 있습니다 . 그런 다음 테스트doctest/1 에서 매크로 를 호출하고 접두사 가 인 경우 주석 에 작성된 코드도 실행합니다 .ExUnit@dociex> defmodule GameTest do use ExUnit.Case, async: true alias GameApp.{Round, Game, Player} alias GameApp.Config, as: GameConfig ################################## doctest GameApp.Game, import: true ################################## @shortcode "ABCD" @player1 Player.create(id: "1", name: "Gamer") setup do [game: Game.create(shortcode: @shortcode, creator: @player1)] end test "create/2", %{game: game} do # ... end # ... end 결론 문서화는 유지 관리 가능한 응용 프로그램 구축 이야기에서 중요한 장입니다 . 엔지니어로서 작업을 문서화하는 데 충분한 시간을 할애하고, 다른 기여자가 문서에 대한 높은 표준을 유지하고 있는지 확인하고, 문서가 관련성 있고 최신 상태이며 완전한 상태를 유지하도록 보호 시간을 옹호하는 것은 우리의 책임입니다.