두고두고 보려고 작성하는, 일 잘 하는 법

[iamminji]

일 잘 하기

어떻게 해야 일을 잘 하는 걸까?
답을 모르겠어서, 책 이것저것 보며 뭔가 마음에 와닿는 것들을 적어보려고 한다.

• 개인적인 의견은 이모지 💡 로 표현하였다.
• 새롭게 알게된 사실, 중요하다고 생각한 것, 잘 지키지 못했던 것들은 ⭐ 로 표현하였다.
• 한번도 생각하지 못했던 것, 보고 좀 놀랐던 건 😮 로 표현하였다.

📖 구글 엔지니어는 이렇게 일한다.

구글 엔지니어는 이렇게 일한다 책을 보고 와닿았던 것들, 알아두면 좋은 것들을 정리해보자

스타일과 가이드 규칙

• 코드는 작성횟수보다 읽는 횟수가 더 많다. (쓰기 간편한 것 보다 읽기 간단한 것에 더 가치를 두자)
• 함수의 구현부를 들여다보지 않고 호출부만 보고 무엇을 수행하는 지 알 수 있게 하자

스타일 가이드엔 어떤 것이 들어가야할까?

• 위험을 피하기 위한 규칙
• 모범 사례를 적용하기 위한 규칙
• 일관성을 보장하기 위한 규칙

코드 리뷰하기

명심하자

• 코드는 자신의 것 이 아니라 협업을 통해 만들어지는 조직의 공동 소유물 임을 인식하자. (코드 리뷰는 이를 위한 좋은 프로세스다.)
• 코드 리뷰는 단 하나의 문제만을 다루는게 가장 이상적이다.
• 코드는 부채다...!!
• ⭐ 코드 리뷰는 이미 결정된 설계에 관해서 왈가왈부하는 시간이 아니다. (대안 설계를 제시하는 자리도 아니다.)

코드 작성자 입장

• 코드는 작성 횟수보다 읽히는 횟수가 더 많으므로 이해하기 쉽게 작성하는게 중요하다
• ⭐ 리뷰할 코드를 작게 유지하자 (하지만 작다 라는 개념은 정량적으로 평가할 수 없다. 알아서 잘 하도록 하자...)
• 필요이상으로 복잡하게 개발하지 않았는지 유의하자.
• 리뷰어가 단 댓글은 모두 TODO 로 취급하자 (의문 없이 수용하라는게 아니라 고민은 해보고 진행할 것. 동의하지 못하면 리뷰어에게 그 사실과 이유를 말할 것)
• 리뷰어와 토론하고 싶다면 대안을 제시하고 한번 더 살펴봐달라고 부탁하자.
• 커밋 설명의 첫 줄에는 어떤 변경인지 잘 요약해야 한다. 커밋 메시지에 구체적으로 무엇을 왜 변경하는지 알려주는 자세한 설명을 작성해야 한다.
• ⭐ 버그 수정은 버그 수정만 하자. 다른 걸 변경하고 싶은 마음을 꾹 참자.

리뷰어 입장

⭐ 리뷰어가 코드베이스 개선에 병목이 되면 안된다. (초기 피드백을) 24시간 안에 할 수 있도록.... 유의하자..!!

• 리뷰어는 자신이 선호한다는 이유로 다른 안을 주장해서는 안된다. (이해하기 더 쉽거나, 기능을 개선하는 리뷰 제외)
• ⭐ 새로운 코드가 완벽하다 고 합의될 때 까지 기다리지 않고 코드 베이스를 개선한다고 인정되면 변경을 승인한다.
• 리뷰어는 작성자가 선택한 설계를 존중해야 한다.
• 리뷰어의 의문은 시간이 지날 수록 가치가 커지므로 고객 입장에서 질문을 하도록 하자.
• 리뷰어는 작성자의 방식이 잘못되었다고 가정하기 전에 그렇게 처리하게 된 이유가 무엇인지 물어보자.
• 리뷰어는 신속하게 피드백해야 한다.
• ⭐ 너무 단편적인 피드백은 삼가자 (이것 저것 조금씩 피드백 하지 말자!)

코드 리뷰 자동화하기

코드 리뷰를 가능하면 자동화하면 좋을 것 같다. 어떻게 자동화할 수 있을까?
구글은 크리틱이라는 도구를 통해 비판적인 리뷰를 받고, 이후에 코드 소유자에게 리뷰를 부탁한다고 한다.

자바를 기준으로 사용할만한 정적 도구들을 조사해보자

• https://github.com/google/error-prone
• https://www.jetbrains.com/qodana/

같이 보면 좋을 것 -> 구글 자바 스타일 가이드 https://google.github.io/styleguide/javaguide.html

문서 작성하기

💡 개인적으로 문서 작성을 좋아하는 편이지만, 적절한 도표 배치와 비문 표현 지양 등 읽기 쉬운 글을 쓰는 건 정말 어려운 것 같다. 또한 글 쓰기에 난이도는 차치하고 문서 버젼 업데이트 역시 귀찮을 때도 있고 깜박할 때도 있어서 이런 것들을 자동화하여 작성자에게 알람을 줄 순 없을까? 이런 고민도 하게 되고.

구글에서는 _문서 자료를 코드처럼 취급 하여 엔지니어링 워크플로에 통합하게 했다고 한다.

문서자료란 무엇일까?

문서 자료 documentation 은 엔지니어가 작업을 끝마치기 위해 작성해야 하는 모든 부수적인 텍스트를 의미한다. (사실 구글에서는 문서 자료 대부분이 코드 주석이라고 한다.)

문서자료는 왜 필요할까?

사실 작성자에게 도움이 된다기 보다는 후임자들에게 이득이 가는 경우가 많다. 문서 자료 역시 작성 횟수보다 읽히는 횟수가 더 많다.

문서 자료는 아래 내용들에 대해서 파악하기 용이하게 해준다.

• 설계를 택한 이유
• 코드를 구현한 방식의 이유 (ex: 내가 왜 이렇게 했을까?)

그리고 작성자에게도 도움이 된다.

• 설계를 다시 돌아보게 해준다.
• 유지보수를 위한 로드맵과 과거 이력을 제공한다.
• 이용자들의 질문이 줄어든다.

문서자료도 코드와 같다

규칙, 스타일이 있고 일관되어야 하고 명확해야 한다.

그래서 구글은 문서 자료를 위한 스타일 가이드도 있다. https://developers.google.com/style

• 내부 정책과 규칙이 있어야 한다.
• 버젼 관리 시스템에 등록되어 관리해야 한다.
• 관리 책임자를 명시해야 한다.
• 😮 변경 시 (문서자료가 설명하는 코드와 함께) 리뷰를 거쳐야 한다.
• 코드상의 버그를 추적하듯 문제를 추적해야 한다.
• 주기적으로 평가 (혹은 테스트)를 받아야 한다.
• 가능하다면 정확성이나 최신 정보 반영 여부 등을 측정해야 한다.
• ⭐ 문서 자료에서는 중복이 때론 유용하다.
• ⭐ 문서 하나는 하나의 역할만 해야한다.
• ⭐ 😮 오래된 문서는 폐기 대상으로 표시하고 (할 수 있다면 최신 정보의 위치 를 알려주자) 더 이상 유효하지 않음을 작성하다.

독자 파악하기

💡 문서 작성에서 가장 중요하다고 개인적으로 생각하는 것은 누가 읽을 것인가 라고 생각한다. 요즘 팀 문서와 사용자들을 대상으로 한 튜토리얼 문서를 작성하면서 가장 관심있게 읽은 파트이다.

• 독자 유형은 차치하고 가능하면 문서는 짧게 쓰는 것이 좋다. (전문가와 초보자 모두를 만족시킬 수 있을지도?!)
• 탐색자 seeker 는 자신이 원하는 것이 무엇인지 안다. 이런 사람들에겐 일관성이 핵심인 문서를 제공한다.
• 배회자 stumbler 는 자신이 원하는 것이 정확히 알지 못한다. 이런 사람들에게는 명료한 글이 효과적이다.

⭐ 튜토리얼 문서라면 모든 단계 하나하나에 고유한 번호를 붙여주자. 그리고 눈으로 확인할 수 있는 입력이나 출력이 있다면 별도로 명시해주자.

문서 자료 유형

종류가 다름을 알고 아래 유형들에 대해서 서로 섞이지 않게 유의하자. 문서는 하나의 목적에 집중 해야 한다.

• 참조용 문서자료 (코드 주석 포함)
• 설계 문서
• 튜토리얼
• 개념 설명 문서
• 랜딩 페이지

주석 잘 작성하기

• 클래스 주석에는 클래스 자신을 문장의 주어로 두고 어떻게 동작하는지를 설명하는 형태로 작성한다.
• 함수 주석은 능동성을 부각하기 위해 동사로 시작해야하고 무슨 일을 하고 무엇을 반환하는지를 작성한다.

테스트

테스트는 왜 작성해야할까? 시스템이 기대한, 의도한 설계대로 잘 동작하는지를 확인하기 위해서이다.

⭐ 테스트는 엔지니어에게 신뢰를 줄 때만 가치를 가진다는 걸 잊지 말자.

💡 요즘 고민 중 하나가 바로 테스트 코드의 유지보수이다.
서비스 코드와 달리 테스트 코드는 가독성을 크게 고려하지 않게 작성 되었고 작성하고 있었다. 그래서 테스트 실패 시 무엇 때문에 실패하였는지, 입력이 어떻게 되어 있는지 파악하기가 어렵고 이 때문에 피로도가 증가하고 있다.
좋은 테스트란 무엇일까? 테스트야 말로 진짜 한번만 작성되고 거의 수정하지 않는 코드인데 어떻게 해야할지 고민이 많다.