올바른 방법으로 골치 아픈 문제와 문서 계약을 저장하세요

계약은 소프트웨어 개발의 필수적인 부분입니다. 개발 비용을 낮추고 개발자의 삶을 더 쉽게 만듭니다. 하지만 문제가 있습니다. 오래된 동화처럼 제대로 문서화되지 않고 팀 전체에 입소문으로 전달되지 않기 때문에 상황이 복잡해지는 경우가 많습니다. 확산되는 동안 계약이 변경됩니다. 갑자기 새로운 세부사항이 나타나고 이전 세부사항은 사라집니다. 결국 팀원들 모두 머리 속에는 각자의 동의하는 그림이 생기고, 그 그림마저도 가끔은 희미해지기도 한다.

더 나쁜 것은 팀이 이러한 계약을 문서화하기 시작할 때 이를 무작정 수행하고 느슨하게 결합된 문서를 엉망으로 만드는 경우가 많으며 그 중 절반은 최신 상태도 아닙니다.

이 기사에서는 계약을 문서화하는 올바른 방법 에 대해 설명하여 도움이 될 것입니다.

그렇다면 어떻게 합의가 도움이 될 수 있습니까? 우리는 이를 문서화해야 할 뿐만 아니라 다음과 같이 해야 합니다.

• 사용하기 쉬웠습니다.

• 이러한 계약을 따르려면 최소한의 노력이 필요합니다.

• 이러한 계약이 여전히 유효한지 이해하기 쉽습니다.

• 이러한 계약이 존재하는 이유를 이해하는 것은 쉬울 것입니다.

• 이상적으로는 자동화되었습니다.

  
  

계약을 분류하는 방법은 다양합니다. 추상화 수준에 따라 나누겠습니다.

• 코드 수준 계약;
• 아키텍처 수준 계약;
• 프로세스 수준 계약.

다양한 수준의 계약에는 이를 문서화하고 다양한 이점을 제공하는 다양한 방법이 필요합니다. 각 레벨을 살펴보겠습니다.

코드 수준 규칙

이러한 계약의 목적은 코드를 통일되고 포괄적이며 읽기 쉽게 만드는 것입니다. 여기 몇 가지 예가 있어요.

• 우리는 작은따옴표 대신 큰따옴표를 사용합니다.

• 이러한 호출을 메소드로 래핑하는 Config 클래스를 제외하고 코드에서 ENV를 직접 호출하지 않습니다.

• 서비스 객체에는 접미어 Service 와 하나의 공개 메소드 call 있습니다.

  
  

이러한 유형의 합의는 독자의 인지 부하를 낮추고 알려지지 않은 코드에 더 빨리 익숙해지도록 돕기 위해 만들어졌습니다. 마틴이 말했듯이, 코드는 작성된 것보다 최대 10배 더 많이 읽혀집니다.

Ruby on Rails 프레임워크에 대한 귀하의 의견에도 불구하고, 이 프레임워크의 핵심에는 convention over configuration 있어 모든 Rails 개발자가 다른 사람의 프로젝트를 열고 즉시 꽤 잘 탐색할 수 있습니다.

그렇다면 이러한 규칙을 문서화하는 방법은 무엇입니까? 린터 도구! 적합한 린터 규칙이 없으면 직접 린트를 작성하세요. 거의 모든 linter에서 이를 수행할 수 있습니다. 여기 의 예가 있고, 의 예가 있습니다.

이러한 규칙에 Linter를 사용하면 다음과 같은 세 가지 이점을 얻을 수 있습니다.

• 개발자는 이에 대해 생각할 필요가 없습니다. linter는 모든 오류를 강조 표시하고 종종 수정하기도 합니다.

• 팀에서 코드 검토를 사용하면 검토자가 이러한 사항에 대해 생각하지 않고 더 중요한 것을 볼 수 있는 시간을 더 많이 갖게 됩니다.

• 개발자는 개발 주기가 시작될 때 문제를 발견하게 되므로 나중에 컨텍스트로 돌아가는 데 시간을 허비하지 않고 즉시 문제를 해결합니다. 계약을 유지하는 것이 더 저렴해집니다.

  
  

보너스 하나 더: 새로운 Linter 규칙을 작성하는 것은 주니어 개발자에게 훌륭한 교육입니다. 이 작업을 완료하는 동안 그는 코드 구문 분석 및 AST 구축에 대해 많은 것을 배우고 언어를 더 깊이 이해하게 됩니다.

아키텍처 수준 규칙

이는 아키텍처를 사려 깊고 일관적이며 균일하게 만드는 것을 목표로 하는 더 높은 수준의 계약입니다. 몇 가지 예:

• 우리는 Python을 사용하여 시스템의 부하가 높은 부분에 일반 서비스와 Elixir를 작성합니다.

• 백엔드는 설명된 형식으로 오류를 반환합니다.

• 각 서비스는 prometheus에서 메트릭을 전송해야 하며, /metrics 엔드포인트에서 메트릭 전송을 위한 포트는 PROMETHEUS_PORT 환경 변수에 의해 구성됩니다.

  
  

이러한 합의는 인지 부하를 줄일 뿐만 아니라 다음 세 가지 문제도 해결합니다.

1. 운영 비용을 절감합니다. 서비스가 동일한 로그 형식으로 동일한 방식으로 시작되고 동일한 지표를 게시하면 서비스를 유지 관리하고 사고에 대처하는 것이 훨씬 쉽습니다.

2. 설계 비용을 절감합니다. 개발자는 매번 처음부터 아키텍처를 설계할 필요가 없습니다. 미리 생각했다면 이제는 기본적인 사항에 대해 걱정하지 않고 특정 기능이나 서비스만 설계하면 됩니다.

3. 통신 비용을 절감합니다. Kafka에서 서버의 응답이나 이벤트 형식이 미리 결정되어 있는 경우 개발자는 매번 상호 작용에 대해 논의할 필요가 없으며 대신 규칙을 참조하기만 하면 됩니다.

   
   

이러한 계약은 더 복잡하므로 두 단계로 수정하는 것을 선호합니다.

1단계 - 설명

ADR(Architecture Decision Record)은 그러한 계약을 문서화하는 도구입니다. 그 매력은 계약과 함께 메타 정보를 캡처한다는 것입니다. 그러한 계약이 채택된 이유; 어떤 대안이 논의되었는지; 마지막으로 개정되었을 때; 그 합의는 아직도 유효합니까?

이를 통해 새로운 팀원은 결정의 이유를 이해하고 주변 사람들에게 이에 대해 묻지 않을 수 있습니다.

ADR은 여러 주요 블록으로 구성됩니다.

1. 이번 합의로 어떤 문제가 해결되나요?

2. 문제 해결을 위해 어떤 옵션이 고려되었으며, 그 옵션의 장점과 단점은 무엇이었습니까?

3. 결국 어떤 선택이 선택됐나요?

   
   

구현 비용 계산과 같은 추가 블록이 있을 수 있습니다.

ADR은 변경 내역과 논의 내역을 볼 수 있는 시스템에 보관하는 것이 더 편리합니다. 제가 선택한 것은 Github와 Notion입니다. 각각 장단점이 있습니다. Github의 장점은 바로 사용할 수 있는 검토 도구와 버전 기록이 있다는 것입니다. Notion은 데이터베이스 및 태그 작업의 편의성으로 인해 좋은 솔루션이 될 수 있습니다. 또한 개발자가 아닌 사람도 쉽게 처리할 수 있습니다.

ADR을 시작하려면 다양한 ADR 템플릿과 사용 방법에 대한 예를 찾을 수 있는 살펴보는 것이 좋습니다.

2단계 - 자동화

ADR은 코드 수준 규칙보다 자동화하기가 더 어렵습니다. 디자인 린터는 아직 발명되지 않았습니다(안타깝습니다!). 그럼에도 불구하고, 어떤 합의 여부에 따라 부분적으로 자동화하는 것도 가능합니다.

언어, 라이브러리 및 인프라에 포함된 서비스에 대한 계약을 위한 서비스 템플릿을 생성하고 업데이트합니다. 그런 다음 개발자는 처음부터 새 서비스를 작성하지 않고 템플릿에서 이를 복사하여 구성된 Dockerfile, 메트릭 게시 등을 즉시 받습니다.

마찬가지로 하나의 애플리케이션 내에서 클래스 생성기를 만들 수 있습니다. 여러 애플리케이션 계층(컨트롤러 => 양식 => 서비스 객체)에 동의했다고 가정합니다. 이 경우 새로운 기능에 대한 모든 레이어를 한 번에 생성하는 간단한 콘솔 명령을 만들 수 있습니다.

이러한 방식으로 자동화할 수 없는 일부 원칙에 동의한 경우 병합 요청이나 추적기의 작업에 자동으로 추가되는 체크리스트를 구성할 수 있습니다. 따라서 개발자는 작업을 전달하기 전에 신속하게 이를 살펴볼 수 있습니다.

프로세스 수준 계약

각 회사에는 프로세스에 대한 많은 계약이 있습니다. 예를 들면 다음과 같습니다.

• 회사의 채용 방식에 대한 설명입니다.

• 릴리스 롤아웃 프로세스에 대한 설명입니다.

• 대규모 작업에 대한 설계 검토 요구 사항입니다.

• 현재 업무와 장애물에 대해 논의하면서 일주일에 두 번 팀 회의를 진행합니다.

  
  

최근까지 저는 이러한 계약이 회사의 성공에 큰 영향을 미치지만 문서화하는 것에 대해 생각하지 않았습니다. 이러한 계약을 문서화하면 위에서 언급한 유형의 이점을 전달할 수 있을 뿐만 아니라 프로세스를 합리화하고 가시적인 측면으로 전환하고 편의성을 고려할 수 있습니다.

나는 에게서 아이디어를 얻었습니다. 그는 ADR(Process Decision Record)과 유사한 도구를 제안했습니다. 유일한 차이점은 아키텍처 결정 대신 프로세스에 대한 결정을 설명한다는 것입니다. 또한 그는 각 PDR에 "재검토 날짜"를 넣을 것을 제안했습니다. 이 날짜는 채택 후 n 개월 후에 문서가 여전히 최선의 방법으로 문제를 해결하는지 확인하기 위해 문서로 돌아가는 날짜입니다. ADR 포함).

자동화의 경우 할 수 있는 일이 거의 없습니다. Jira에서 워크플로를 설정하거나, 회의 알림을 설정하거나, 주간 결과 프레젠테이션을 자동으로 준비하는 봇을 생성하여 일부 프로세스를 자동화할 수 있습니다(저는 외국 회사에서 이 작업을 수행했습니다).

그러나 프로세스를 실제로 자동화할 수 없는 경우가 많으며 주요 목표는 프로세스를 따르지 않는 것보다 따르기 쉽게 만드는 것입니다. 그럼에도 불구하고 프로세스를 이미 쉽게 따라할 수 있더라도 계약을 문서화하는 것은 여전히 도움이 될 것입니다. 공식화 및 합리화를 통해 프로세스를 개선할 수 있습니다.

결과는 어떻습니까?

문서화 및 후속 자동화는 이점이 있습니다. 개발에 소요되는 시간이 줄어들고, 애플리케이션의 지원이 더욱 용이해지며, 프로세스가 더욱 스마트해집니다.

이 모든 것이 불필요한 관료주의라고 생각할 수도 있습니다. 왜냐하면 "우리는 좋은 사람들이기 때문입니다. 우리는 그것 없이도 코드를 개발할 수 있습니다." 그러나 실제로 합의를 통해 상당한 시간과 비용을 절약하고 직원의 신경 세포를 보호할 수 있습니다. 물론, 절대적으로 처리하고 계약에 위배되는 모든 것을 거부할 필요는 없습니다. 이는 계약을 업데이트해야 하거나 처음에 계약의 일부 측면에 대해 생각하지 않았다는 신호일 수 있습니다.

아직 팀에서 계약 문서화를 시작하지 않았다면 낮은 추상화 수준에서 높은 추상화 수준으로 이동하세요. 코드 수준 계약에서 시작한 다음 아키텍처 수준, 프로세스 수준만 처리하세요. 계약 문서는 팀에서 개발하는 습관이며 덜 추상적인 개념으로 시작하는 것이 훨씬 쉽습니다.

또한 모든 유형이 기사에 설명되어 있는 것은 아닙니다. 예를 들어 설계 계약을 라이브러리 구성 요소로 문서화할 수 있습니다.

각각의 새로운 유형의 계약은 동일한 세 단계를 거칩니다.

1. 문서화하는 방법을 알아보세요.

2. 자동화하는 방법을 알아보세요.

3. 시간이 지남에 따라 유지하는 데 필요한 것보다 더 많은 리소스를 절약하도록 하십시오.

   
   

그리고 마지막 것. 문서화 과정에서 기존 계약 중 일부가 명백히 정당화되지 않고 팀의 시간을 낭비하며 일반적으로 해롭다는 사실이 발견될 수 있지만 이미 익숙해졌습니다. 이 경우 팀 마음속에 있는 습관의 장벽을 극복하고 때로는 합의를 받아들이는 것보다 거부하는 것이 더 중요하다는 점을 팀에게 설득해야 합니다. 그러나 그것은 완전히 다른 이야기입니다.