책 정보
https://book.naver.com/bookdb/book_detail.nhn?bid=15513595
개발자의 글쓰기 : 네이버 도서
네이버 도서 상세정보를 제공합니다.
search.shopping.naver.com
서론
6년동안 SM업무만 해오다가 이직과 동시에 개발 부서에 들어오게 되면서
가장 처음 겪었던 난관 중에 하나가 변수, 메소드 이름짓기였다.
이전까지 내가 해왔던 업무는
고객이 고쳐달란 데이터 긴급반영 해주고, 소스 구현내용 물어보면 설명해주는 정도..
개발과 거리가 멀었을 뿐더러 애초에 이름짓기가 왜 필요한지도 모르는 수준이었다.
그런데 이 곳에 오고 처음으로 PR 리뷰라는 것을 하게 되면서
좋은 네이밍이 동료들에게 얼마나 도움이 되는지, 변경 이력을 기록하는 것이 얼마나 중요한지
점차 알아가게 되었다 (아직 알아가는 중이다.)
사실 이 책은 위에서 언급한 네이밍 룰 위주로 돌아가는 책은 아니다.
전반적인 개발자가 가져야 할 글쓰기 소양에 대해 설명하고 그게 왜 필요한지 설명해준다.
이 책만 읽고는 스킬업 하기 어렵겠지만 적어도 개발자의 글쓰기 소양이 왜 필요한지는 확실히 알 수 있을 것 같다.
본론
아래는 읽다가 기억 남았던 부분들을 기록해 놓은 것이다.
영어 단어 선택하기
개발을 하다보면 영어 단어의 반댓말, 비슷한 말을 찾아내야 할 때가 많다.
흔히 쓰이는 예로 HTML에선 show/hide 가 있을 것이고 Java 에선 get/set 도 예가 될 수 있을 것이다.
영어 단어를 선택하는 과정에 있어서
그 단어가 기능을 잘 설명하는 것도 중요하지만 다른 유사 단어들과 비교했을 때 그 뜻이 명확한지 (잘 구분되는지)
반대되는 단어가 이미 쓰이고 있다면 해당 단어와 반대말 쌍을 잘 이루는지도 따져봐야 할 것이다.
아래는 반댓말 예시이다
- header/footer , under/over , before/after , input/output , open/close , import/export
아래는 비슷한 말 예시이다.
- stop (잠시 중단, 재시작 가능) / end (완전 중단, 재시작 불가) / finish (완료, 재시작 불필요) /
pause (일시 중단, 언제든 재시작 가능) / hold (의도에 의한 중단, 일시 보류)
- change (내용 단순 변경) / modify (잘못된 것 수정) / revise (기존과 달라짐. 없던 것을 덧붙임)
- parameter (매개변수. 함수에 정의한 변수) /. argument (전달인자. 함수 호출 시 전달되는 값)
Java Naming Convention
- 파스칼 표기법으로 클래스 이름 짓기
* 파스칼 표기법 : 모든 단어 첫 글자를 대문자로 쓰는 방식 (UpperCamelCase)
- 카멜 표기법으로 함수, 변수 이름 짓기
* 카멜 표기법 : 첫 단어를 빼고 나머지 단어의 첫 번째 글자만 대문자로 쓰는 방식 (lowerCamelCase)
- 상수는 모두 대문자로 쓰고 언더스코어(_)로 단어를 연결한다.
- 패키지와 모듈은 모두 소문자로 쓴다.
참고 링크 : https://brunch.co.kr/@goodvc78/12
좋은 이름의 기준
- 검색이 잘되는 단어를 사용하자
- 중요한 단어를 앞에 두자
- 기억하기 쉬운, 발음이 어렵지 않은 단어를 사용하자
사용자와 소통하는 에러 메시지
- 에러 메시지도 친절하게 쓰자
- 깨진 링크는 개발자의 책임이다
. 브로큰링크체크닷컴 (https://www.brokenlinkcheck.com)
. 구글서치콘솔 (http://www.google.com/webmasters/tools/)
버전의 의미
- 첫 번째 자리를 올렸을 때 : 전면적인 업그레이드여서 이전 버전과 호환이 되지 않는다고 볼 수 있다.
프로그램 명맥은 잇겠지만 다른 프로그램이라고 봐야 한다
- 두 번째 자리를 올렸을 때 : 새로운 기능을 추가했을 때 이전 숫자와 일부 호환될 수는 있지만 이전 버전에선 새로운 기능을 사용할 수 없다
(1.2.X에서 1.3.0 의 기능을 사용할 수 없다.) 두 번째 자리가 올라가면 세 번째 자리는 초기화 된다.
- 세 번째 자리를 올렸을 때 : 간단한 패치를 의미한다. 이전 버전과 호환된다 (1.2.2면 1.2.1)
버전에 대한 가이드로 깃허브 공동창업자인 톰 프레스턴 베르너가 정한 Semantic Versioning을 제시한다.
김대현 님이 번역한 것이 있으니 자세한 건 링크 참고 (https://semver.org/lang/ko/)
- 버전은 X.Y.Z 형태로 한다. 각각은 자연수로 독립적으로 증가한다. 점(.)은 소수점이 아니라 구분기호다.
X = Major, Y = Minor, Z = Patch
- X가 0 인 것은 초기 내무 개발에서만 사용하고 최초 공개 API 는 1.0.0 로 한다.
- X는 기존 버전과 호환되지 않는 변화가 있을 때만 1씩 올린다
- Y는 기존 버전과 호환되는 새로운 기능이 추가됐을 때 1씩 올린다.
- Z는 기존 버전과 완전히 호환되면서 작은 규모의 패치가 있을 때 1씩 올린다. X, Y를 올리면 Z는 초기화된다.
장애보고서
- 장애 내용 : 사용자 결제 불가 (10:00 ~ 11:00 , 1시간)
- 장애 영향 : 장애 중 결제 시도 100건 -> 1시간 후 결제 비율 10% (평균 50%)
- 장애 원인 : 서버 쪽 결제 모듈 변경 시 모듈 인터페이스 함수를 수정했으나 프론트에서 기존 함수로 호출하여 에러 발생
- 조치 상황 : 서버 쪽의 바뀐 함수를 호출하도록 프론트 코드 수정
- 조치 결과 : 결제 기능 정상 작동
- 핵심 원인 : 서버 쪽과 프론트 쪽 커뮤니케이션 단절
- 향후 대책 : 서버, 프론트 팀장이 소통 방법 협의하여 보고
개발 가이드를 작성하기
스크린샷과 함께 개발 가이드를 작성할 때
[푸시서비스 설정]
1. 사이드바 메뉴에서 설정을 클릭하여 확정메뉴를 펼칩니다.
2. 푸시를 선택하여 푸시 설정 화면으로 이동합니다.
3. 푸시 섹션에서 푸시 사용 버튼을 On 으로 켭니다
...
[푸시 서비스 설정]
푸시 서비스를 설정하려면 (1)설정 > (2)푸시 화면에서 (3)푸시 사용을 On으로 킵니다.
글을 쓸 때 독자를 생각하자
- 이 글을 왜 쓰는가?
- 이 글을 읽는 독자는 누구인가?
- 이 글을 읽는 독자에게 무엇을 말하려고 하는가?
- 이 글이 주장하는 바는 무엇인가?
- 이 글이 주장하는 바의 근거가 분명한가?
댓글