[Hyperledger Indy Docs] Indy Node: 12. Code quality requirements guideline

이 글은 Hyperledger Indy의 공식 문서를 번역한 것입니다.
원본 사이트 : https://hyperledger-indy.readthedocs.io/projects/node/en/latest/write-code-guideline.html

 

새로운 코드를 사용하여 PR을 보내기 전에 다음 항목을 고려해야합니다.

 

General items(일반 항목)

• 새로운 기능을 구현하기 전에 디자인 문서를 design 폴더(markdown 또는 PlantUML 다이어그램)로 보내는 것을 고려하십시오.
• 새로운 기능 또는 수정 사항이 테스트에 포함되는지 확인하십시오(TDD에 따라 시도)
• 변경 사항에 따라 설명서가 업데이트되었는지 확인하십시오(docs 폴더 참조). 특히 트랜잭션 또는 request 형식을 변경하면 transactions 및 requests를 업데이트하십시오.
• 증분 리팩토링 접근법을 따르십시오:
  • 주저하지 말고 코드를 개선하십시오
  • 코드에 문제가 있으면 TODO 및 FIXME 주석을 넣으십시오.
  • 문제가 발생하면 Indy Jira에 티켓을 기록하십시오.

 

Code quality items(코드 품질 항목)

현재 코드는 완벽하지 않으므로 언제든지 개선하십시오.

• PEP 8을 따르고 모든 파일에서 동일한 코드 스타일을 유지하십시오.
  • Naming. 함수용 snake case, 클래스용 camel case, 등
  • 의도적으로 공개하지 않은 클래스 멤버에게 밑줄로 시작하는 이름을 지정하십시오. 이 멤버들은 그들이 속한 클래스 밖에서 사용하지 마십시오.
  • 모든 퍼블릭 모듈 및 함수/메소드에 대한 Docstring. 인수 목록 설명에 특별한 주의를 기울이십시오.
  • 퍼블릭 함수의 인수의 유형에 대한 주석
  • 퍼블릭 함수에 대한 리턴 타입 주석 달기
  • 개발자 환경 및 CI에서 flake8을 사용 (flake8 검사가 통과되지 않으면 빌드 실패). (프로젝트 루트에서 flake8 .을 실행하여 확인할 수 있습니다; pypi에서 flake8을 설치할 수 있습니다: pip install flake8)
• 상속과 다형성
  • 추상 클래스를 작성할 때 ABC를 사용하여 모든 필드가 후속 작업에 구현되도록 하십시오.
  • 다중 상속 대신 composition 선호
  • 깊은 계층 생성 금지
  • 유형 검사(type(instance) == specific_subclass) 금지. 우리는 어떤 장소에 그것들을 가지고 있으며 끔찍합니다. 대신 다형성을 사용하십시오.
  • 인터페이스 또는 추상 클래스가 있는 경우 특정 인스턴스 대신 어디에서나 사용해야합니다.
  • 서브 클래스의 메소드가 인터페이스/추상 클래스의 선언과 완전히 호환되는지 확인하십시오.
• 우려의 분리
  • 우려 원칙 분리
  • 가능한 한 독립적인 구성 요소 만들기
• 높은 커플링 피하기
  • 일부 클래스(예: Node 및 Replica)는 서로에 대한 참조가 있으므로 일종의 "spaghetti code"
• 병렬 배열 대신 클래스 사용
• 명확하고 복제되지 않은 유틸리티
• 분해
  • 너무 긴 함수와 클래스가 있습니다. 예를 들어 클래스 Node에 2000 줄 이상의 코드가 있으면 논리에 대한 이해가 복잡해집니다.
  • 이것은 집계, 구성 및 상속에 의해 작은 클래스에서 이러한 클래스 또는 함수를 구조화하여 해결할 수 있습니다.
• 여러 개의 동봉된 if-elif-else 문이 없습니다.
  • 여러 개의 동봉된 if-else 문이 포함된 코드를 읽기가 어렵습니다.
  • 메소드의 시작 부분에서 일부 조건을 확인하고 즉시 리턴하십시오.
• 좋은 변수와 클래스 이름을 선택하십시오.
  • 특히 퍼블릭 API의 경우 변수 및 이름 클래스를 명확하게 만듭니다.
  • 퍼블릭 API에서 불명확한 약어 피하기
• 콜백 대신 asyncio 사용
  • 마치 메소드 호출처럼 보이고 동작합니다. 코루틴이 완료될 때까지 추가 코드가 실행되지 않습니다.
  • 콜백 준비가 필요하지 않습니다 - 코드가 깨끗합니다.
  • 문맥을 위반하지 않습니다. - 코루틴에서 발생한 예외는 메소드에서 발생한 예외와 동일한 스택 추적을 갖습니다(콜백에서 발생한 예외는 그렇지 않습니다)
  • 코루틴 호출을 연결하는 것은 쉽습니다.
  • 필요한 경우 미래에 코루틴을 쉽게 감싸고 비 차단 방식으로 실행할 수 있습니다.
• Actor 모델 사용을 고려하십시오(더 나은 코드 품질과 성능을 달성하기 위한 리팩토링을 위한 장기 목표입니다)
• pool의 성능에 대해 생각

 

Test quality items(테스트 품질 항목)

• 좋은 테스트 작성
  • 모든 테스트가 깨끗하고 명확하지는 않습니다.
  • 테스트를 먼저 작성하여 TDD를 따르십시오.
  • 가능한/필요한 경우 단위 테스트 진행
  • 가능하면 'module' 레벨 fixture를 사용하지 마십시오.
• 가능하면 모든 테스트에서 indy-sdk를 사용하십시오. 몇 가지 이유로 indy-sdk를 사용할 수 없는 경우(예: indy-sdk에 필수 기능이 없음), Indy-sdk Jira에 티켓을 기록하고 테스트에 TODO 주석을 추가하십시오.
• nodeSet fixture가 아닌 txnPoolNodeSet을 사용하십시오. nodeSet은 곧 더 이상 사용되지 않을 것입니다.
• fixture 가져오기
  • fixture 가져오기는 IDE에서 강조 표시되지 않으므로 누군가가 실수로 제거할 수 있습니다. 이를 피하기 위해 fixture를 포함하는 패키지의 conftest 또는 일부 상위 레벨의 패키지 conftest로 이동하면 fixture가 자동으로 해결됩니다. 여전히 fixture를 가져오기 하려는 경우, IDE에 대해 다음 힌트를 사용하여 가져오기를 사용하지 않는 것으로 표시하지 않고 가져오기를 최적화 할 떄 제거하지 않도록 표시하십시오: # noinspection PyUnresolvedReferences
• 실제 환경에서와 동일한 통합 테스트에 동일한 구성 및 파일 폴더 구조를 사용하십시오. 현재 모든 테스트는 Indy-node 서비스와 동일한 파일 폴더 구조(indy-file-structure-guideline 참조)를 따르지만 폴더는 tmp 테스트 폴더 내에 작성됩니다.