▲

GN⁺: esbuild와 Redis, 훌륭한 아키텍처 문서를 갖춘 두 개의 오픈 소스 프로젝트

 (johnjago.com)
27P by neo 8달전 | favorite | 댓글 2개
  • esbuild와 Redis는 뛰어난 문서화를 가진 코드베이스의 예시임
  • README, 변경 로그, 아키텍처 문서, 코드 주석을 통해 새로운 사용자도 코드베이스의 구조, 작동 방식, 그리고 그 이유를 이해할 수 있음.
  • 코드와 소프트웨어 아키텍처 문서화를 개선하고자 하는 개발자에게 좋은 사례 연구가 됨.

좋은 문서화가 중요한 이유

  • 소프트웨어 작성 시, 특히 다른 사람이 코드베이스를 볼 때나 기여할 때, 또는 나중에 본인이 다시 참조할 때 좋은 문서화가 필수임.
  • 소프트웨어 사용자는 종종 누락된 문서화로 인해 어려움을 겪음.
  • 코드베이스에 기여하는 경우, 문서화의 질이 좋을수록 빠르게 기여할 수 있음.
  • 문서화의 질은 저자, 기여자, 또는 사용자의 경험에 직접적이거나 간접적으로 영향을 미침.
  • 좋은 문서화의 이점은 시간 절약, 오픈 소스 프로젝트의 외부 기여 증가, 과거 결정의 기록, 더 많은 사용자의 접근성, 사고 구조화 및 문제점 발견 등 다양함.

esbuild의 문서화

  • esbuild는 Evan Wallace가 만든 JavaScript 번들러임.
  • esbuild의 README는 도구의 최종 사용자에게 초점을 맞추고 있음.
  • 문서의 주요 섹션 링크와 "왜?"라는 섹션을 통해 다른 번들러보다 esbuild를 선택해야 하는 이유를 간략하게 설명함.
  • esbuild의 아키텍처 문서는 docs 디렉토리에 architecture.md와 development.md 파일로 구성됨.
  • 아키텍처 문서는 디자인 원칙을 설명하고, 텍스트뿐만 아니라 개념을 설명하는 그래픽도 포함함.
  • esbuild의 변경 로그는 요약, 확장된 설명, 변경 전후의 예제 코드를 포함하여 상세함.

Redis의 문서화

  • Redis는 메모리 내 데이터베이스임.
  • Redis의 README는 esbuild의 README와 유사한 좋은 특성을 공유하면서도, 기여자와 최종 사용자 모두에게 초점을 맞춤.
  • Redis의 내부에 대한 섹션은 소스 코드의 레이아웃과 주요 파일에 대한 설명을 포함함.
  • Redis 소스 코드 내의 코드 주석은 단일 코드 라인에 대한 여러 단락의 설명을 제공함.

마무리

  • 많은 오픈 소스 프로젝트들이 훌륭한 문서화를 가지고 있음.
  • esbuild와 Redis는 특히 뛰어난 문서화로 인상적임.
  • 문서화는 단기적인 시간 제약을 초래할 수 있지만, 장기적으로 시간을 절약해줌.
  • 많은 사람들이 사용하거나 기여하는 프로젝트에서 문서화를 하지 않는 것은 재고해볼 필요가 있음.

GN⁺의 의견

  • esbuild와 Redis의 문서화 사례는 개발자들에게 코드베이스의 이해와 유지보수를 용이하게 만드는 문서화의 중요성을 강조함.
  • 문서화는 프로젝트의 지속 가능성을 높이고, 커뮤니티의 참여를 촉진하는 핵심 요소임.
  • esbuild의 경우, 빠른 JavaScript 번들러로서의 기능 외에도 훌륭한 문서화가 프로젝트 성장에 기여한 것으로 보임.
  • Redis는 복잡한 인메모리 데이터베이스 시스템을 쉽게 이해할 수 있도록 도와주는 문서화로 인해 개발자 커뮤니티에 긍정적인 영향을 미침.
  • 이러한 사례들은 다른 오픈 소스 프로젝트에도 문서화의 중요성을 전파하는 데 도움이 될 수 있으며, 특히 초급 소프트웨어 엔지니어들이 자신의 프로젝트를 문서화하는 방법에 대한 이해를 돕는 데 유용함.
▲
laeyoung 8달전  [-]

esbuild는 README.md 파일도 그렇지만 글에서 소개된 architecture.md 파일이 너무 아름답네요!

답변달기
▲
neo 8달전  [-]
Hacker News 의견

  • Redis의 창시자 Antirez가 자신의 블로그에 코드 주석에 대한 생각을 상세히 설명한 글을 작성함. Redis에서 사용되는 9가지 유형의 주석을 식별함.

    • 많은 사람들이 중요하지 않다고 생각하는 "가이드 주석"의 사용에 놀랐음.
    • Antirez는 이러한 주석이 코드 이해를 돕는 데 가치가 있다고 결론지음.
    • Antirez의 글

  • 프로젝트 문서화가 사용자/개발자/기여자에게 어떻게 훌륭할 수 있는지에 대한 구체적인 예와 스크린샷을 포함한 잘 작성된 기사.

    • 자신의 작업과 부수적인 프로젝트에 대해 성찰하게 만들며, 문서를 개선하여 이해를 돕는 방법에 대해 생각하게 함.
    • 개발자로서 성장하면서 문서와 테스트를 더 많이 작성하게 됨. 일부 프로젝트는 실제 코드보다 문서와 테스트가 더 많음.
    • 좋은 문서를 작성하는 것은 코드를 작성하는 것과 다른 기술 세트를 요구한다는 의견이 있음. 때로는 기술적이지 않거나 개발에 집중하지 않는 사람이 설명하는 데 더 나을 수 있음.
    • 자동 생성된 문서도 유용할 수 있으며, 단독으로만이 아니라 추가 참조 자료로서의 가치가 있음.

  • 저장소의 품질에 대한 관리자들의 관심을 보여줌.

  • "The Architecture of Open Source Applications" 시리즈를 떠올리게 함. 흥미로운 통찰력이 있음.

  • GitLab의 문서가 매우 좋다는 평판이 있지만, 직접 사용할 필요가 많지 않았음. 그들의 아키텍처 문서가 좋은지에 대한 의문.

  • Postgres 프로젝트도 문서, readme 파일, 코드 주석에 상세한 주의를 기울임.

  • esbuild 프로젝트의 아키텍처 문서화에 깊은 인상을 받음. 과거에 작업했던 코드베이스에 이런 문서가 있었다면 좋았을 것임.

    • 이러한 수준의 아키텍처 문서화를 가진 다른 프로젝트 예시에 대한 질문.

  • 오픈 소스 프로젝트의 변경 로그를 매우 좋아함. 이익을 추구하는 다른 엔티티보다 훨씬 전문적이고 유익함. ING 은행의 앱 변경 로그가 유머러스하기보다는 정보 제공에 집중해야 한다는 비판.

  • "오늘날 자유 소프트웨어 커뮤니티에서 가장 큰 결핍은 소프트웨어가 아니라, 자유 소프트웨어와 함께 포함할 수 있는 좋은 자유 문서의 부족이다."

    • gdb 매뉴얼 인용.

  • Redis가 더 이상 오픈 소스가 아니라는 것을 언급함. Redis는 Redis Source Available License v2 (RSALv2)와 Server Side Public License v1 (SSPLv1) 하에 "소스-사용 가능" 소프트웨어임.

    • Redis Stack과 Redis Ltd.가 만든 모든 Redis 모듈(예: RediSearch, RedisJSON, RedisGraph, RedisTimeSeries, RedisBloom)은 RSALv2와 SSPL로 이중 라이선스됨.
    • Redis Enterprise는 폐쇄 소스이며 Redis Ltd.로부터 상업 라이선스가 필요함.
    • 이전 버전의 Redis는 3-clause BSD 라이선스(자유롭고 오픈 소스) 하에 있음. 라이선스 변경은 소급 적용되지 않으며, 변경 전의 모든 소스 코드와 릴리스는 원래의 3-clause BSD 라이선스를 유지함. 해당 조건을 준수하는 한, 이러한 버전을 무기한 사용할 수 있음.
    • Redis 라이선스
    • BSD 라이선스
답변달기