Dayoung

Dayoung

Be-Developer

© 2024

Dark Mode

SoftwareEngineering at google : 프로세스
Apr 3, 2023
  • softwareEngineering,
  • study

08 스타일 가이드와 규칙

  • 구글의 스타일 가이드에 담긴 결정들은 구글 코드베이스를 지속가능하게 관리하기 위한 규칙.

    규칙 만들기

    기본원칙

  • 규모와 시간 양쪽 측면에서 탄력적인 엔지니어링 환경이 지속되도록 하는것.
  • 개발환경의 복잡도를 관리하고 엔지니어들의 생산성을 증대시켜 코드베이스를 관리가능하게끔 유지하는것.
    1. 규칙의 양을 최소화하라.
    • 너무 자명한 규칙은 빼자.
      1. 코드를 읽는 사람에게 맞추어야한다.
    • 쓰기에 간편한 < 읽기에 간단한
    • 변수와 타입이름을 서술식으로 길게 지정하는게 더 낫다.
    • 설계의도를 소스코드에 명시하지않으면 읽는사람이 파악해야해서 추가부담이다.
    • 문서화 주석 /** **/ : 코드의 설계나 의도 설명
    • 구현 주석 // : 주의할점, 까다로운 로직 설명, 중요한 부분 강조
      1. 일관되어야한다.
    • 일관성이 주는 이점
      • 전문가가 분석학기 쉽다.
      • 중복을 찾기 쉬워진다.
      • 공백수같은 일관된 규칙에서 의미있는점은, n칸 같은 수치가 아니라 ‘단하나의 답’을 사용한다는 일관성.
      • 자동화해주는 도구를 제작할 수 있다ㅣ.
      • 팀원을 유연하게 재배치할 수 있다. (적응이 빠르기때문)
    • 구글에 스타일규칙을 변경하자는 제안이 들어왔을때, 일관성 추구보다 대규모 수정이 더 큰 비용이었으며, 일관성을 지키기위해 현재 규칙을 유지하기도 했다.
    • 표준을 지키자 (tab 공백갯수 = 4)
      • 수명이 길고 확장될 가능성이 큰 코드라면, 언젠가 외부코드와 상호작용하고 심지어 바깥에서 코드생을 마감할 수있어 표준을 지키는것이 유리하다.
        1. 오류가 나기 쉽거나 예상치 못한 동작을 유발하는 구조를 피한다.
    • 구글의 파이선가이드는 reflection 등의 기능 사용을 제한한다.
      1. 꼭 필요하다면 실용성을 생각해 예외를 허용하자.
    • 성능
    • 상호운용성 (외부코드와의 일관성 등)

      스타일 가이드 내용

      1. 위험을 피하기 위한 규칙
      2. 모범 사례를 적용하기 위한 규칙
    • 포맷팅 규칙을 일관되게 적용하여 코드 전체의 가독성을 높이는것
    • 새롭거나 아직 널리 이해되지 못한 언어기능 사용을 제한하기도 한다.
      • 엔지니어 전반이 기능으 습득할때까지 방어
      • 모범사례가 만들어지기까지 기다리는 효과
        1. 일관성을 보장하기 위한 규칙

규칙 수정하기

  • 규칙을 우회하는데 에너지를 쓰고있다면 그 규칙에 기대했던 트레이드오프를 재검토해야한다.
  • 각 결정에 이른 근거문서를 남기면 규칙변경 타이밍을 알기 쉽다.
    • 규칙을 추가할때는 장단점과 잠재적인 파장을 분석하고, 결정을 실행하는데 수반되는 변경량이 구글규모에서 무리가 없는지 검증하는데 많은 시간을 쓴다.

      프로세스

  • 스타일가이드에는 결정에 도다른 상세한 근거가 있으므로, 문제가 주어지면 현시점에서는 다른 결론에 도달할 수 있는지 다시 평가할 수 있다.

    스타일 중재자

  • 프로그래밍 언어별로 경험많은 전문가 그룹이 스타일 중재자라고 불린다.
  • 스타일 가이드 수정은 투표가 아닌 합의로 이루어지기때문에, 중재자가 홀수인원이 될 필요가 없다.

    예외

  • 특정상황에서는 예외를 허용하기도 할텐데, 합당한 면제사례가 많아진다면 규칙을 다시 고민하여 더 명확하게 가다듬거나 수정해야한다는 신호일 수 있다.

    지침

  • 지침 : 모범사례를 문서로 남긴것, 되도록 따라야하는 대상이다.
  • 예
    • 올바로 구현하기 어려운 주제에 관한 언어별 조언
    • 언어의 최신 버전에서 소개된 새 기능의 상세설명과 적용하는 방법에 관한 조언
    • 구글 라이브러리가 제공하는 중요한 추상 개념과 데이터 구조 목록

      규칙 적용하기

  • 모범사례를 숙달하도록 정규교육
  • 문서들을 최신화하는데에도 자원 투자
  • 코드리뷰

    오류 검사기

    코드 포맷터

09 코드리뷰

코드 리뷰 흐름

코드는 부채다

  • 새 코드를 추가하기전에, 중복확인이 먼저 이루어져야하며, 새로운것을 설계할때는 코드 작성전 관련 그룹과 대화해보아야 한다.
  • 코드리뷰는 전에 내린 설계를 번복하거나 재논의하는 자리여서는 안된다.
  • 코드 리뷰 과정 자체를 기존 결정을 다시 논의할 기회로 보아서는 안된다.

    코드리뷰 @ 구글

  • approve를 받기위해 통과해야하는 세가지 리뷰
    1. 다른 엔지니어로부터 ‘정확성’ 과 ‘용이성’ 평가
    2. 디렉터리 소유자로부터의 평가
    3. 가독성 인증자로부터의 가독성 승인
  • 세가지를 다 해줄수있는 리뷰어 한명에게 받는경우가 많음.
  • 역할을 셋으로 나눔으로서 코드리뷰프로세스가 유연해지고, 리뷰어들이 보아야하는 측면이 다르므로 더 전문적으로 볼 수 있다.

    소유권

  • repo를 여러개로 쪼개거나 저눔ㄴ지식을 갖추고 레포의 각 부분을 책임져줄 사람을 명시하는 방식.
  • OWNERS 파일에 명시하고, 되도록 적은이원으로 제한하여 책임이 명확하게 드러내도록 해야한다.
  • 소유자는 담당코드들을 본인이 잘 이해하고있거나 잘 이해하는 사람을 찾아낼 수 있어야 한다.

    코드리뷰의 이점

    1. 코드가 정확한지 확인해준다.
    • 정확성 평가가 주관적으로 흘러가지 않도록 하기 위해 일반적으로 변경 작성자가 선택한 방식을 존중해주어야 한다.
    • 이해하기 더 쉽거나, 기능을 개선하는 효율적인 대안인경우에만 대안을 제시해야한다.
      1. 변경된 코드를 다른 엔지니어도 잘 이해한다. (용이성)
    • 리뷰어는 작성자가 선택한 설계를 존중해야한다.
    • 작성자는 비판이 있다고해서 기존 접근법이나 로직을 바꾸어야할 필요는 없지만, 설명을 더 명확하게 해야할 필요는 있다.
    • 리뷰어가 LGTM(Looks Good To Me)를 주었다는것은 해당 코드가 의도한 일을 정확히 수행하면서 이해하기 쉽다는 뜻.
      1. 코드베이스가 일관되게 관리된다.(일관성)
    • 리뷰어는 코드가 코으베이스의 표준을 얼마나 잘 따르는가를 평가할 수 있다.
    • 가독성 승인자의 임무
      • 프로그래밍 언어의 모범 사례들을 잘 따라야 한다.
      • 다른 코드들과 일관되어야한다.
      • 필요이상으로 복잡하지 않아야한다.
        1. 팀이 소유권(주인의식)을 더 강하게 느낄 수 있다.
    • 요청 직전이 자신이 변경한것을 다시 훑어보고 빠진것은 없는지 확인하기에 가장 좋은 ㅅ히간이다.
      1. 지식이 공유된다.
    • 정보가 교환되며 지식공유를 촉진시킨다.
    • 대규모 리팩터링을 포함하는 코드리뷰는 새로운 패턴을 알리는 자리로도 활용된다.
      1. 코드리뷰 자체의 기록이 남는다.

모범사례

리뷰어

  • 그 방식이 잘못되었다고 가정하기전에 그렇게 처리된 이유가 무엇인지 물어보는것이 좋다.
  • 24시간안에 리뷰하지못할것같다면, '변경은 확인했고, 최대한 조속히 검토하겠다’ 라고 댓글이라도 달자.

    코드 작성자

  • 코드를 이해하기 쉽고 유지봇후가 쉽게 만드는 일도 코드 작성자의 책임이다.
  • 동의하지 않는 댓글에는 이유와 동의하지않는 의사표현을 하자.
  • 제안자에게 감사표현을 해주어야 한다.
  • 작은 변경 (200줄 이하)
  • 변경설명 잘쓰기 : pr 타이틀, 머지커밋에 연관된 수정 여러개를 포함하는 변경이라면, 그 모두를 간략하게라도 열거해야한다.
    • 리뷰어가 코드를 이해하지 못한다면, 구조를 개선하거나 주석을 더 잘 달아놔야한다는 신호일 수 있다.
  • 리뷰어는 최소한으로, 리뷰어를 추가해서 얻는 가치보다 비용이 훨씬 빠르게 증가할 수 ㄷ있다.
  • 리뷰어들은 서로 다른 관점에서 바라보도록 역할을 조율한 후 진행해야한다.

    코드리뷰 유형

    1. 그린필드 리뷰와 새로운 기능 개발
    • 코드리뷰와 별개로 설계리뷰를 강도높게 진행한다.
    • 설계문서를 함께 검토하기도 하고, 공개된 API에 단위테스트가 존재해야한다.
      1. 동작 변경, 개선, 최적화
    • 코드삭제는 코드베이스를 건실하게 만드는 좋은 방법
    • 최적화를 하려면 벤치마크 테스트를 미리 준비해두는것이 좋다.
      1. 버그 수정과 롤백
    • 버그 수정은 온전히 그 버그를 잡는데만 집중해야한다.
    • 관련 테스트도 함께 수정하여 버그가 재발할 시 알려주도록 해야한다.
      1. 리팩터링과 대규모 변경

회고

  • pr 프로세스, 리뷰어에관한 표준이 없었던것 같다.
  • 리뷰 담당자별로 다른 측면을 본다면 리뷰 집중도와 전묺성등 장점이 많을듯.
  • 소유권 명시 추가해보자
  • 코드 리뷰 과정 자체를 기존 결정을 다시 논의할 기회로 보아서는 안된다.
  • 작은 변경 : 피처가 커지면, 피처의 피처를 만들어서라도 크기를 줄이자.
  • 설계에 대한 리뷰는 신기능 개발일때만 집중, 리뷰어는 작성자가 선택한 설계를 존중해야한다.