[좋은 코드, 나쁜 코드] 5장. 가독성 높은 코드를 작성하라

코드 자체로 설명이 되도록 작성해보자.

서술적인 이름

const name = () => {}

보다는

const getTeamName = () => {}

로 작성하자.

name이라고 하면 의문이 들 수 있는데, getTeamName라고 하니 반환 값의 정보를 알 수 있어 추가적으로 코드를 들여다보지 않아도 되는 이점이 있다.

이름이 길어지더라도 명확하게 작성하는 것이 좋은 것 같다.

주석문의 활용

하지만 이름을 명확히 지었다고 해서 다른 개발자에게 명료하게 전달되리라 보장할 수는 없다.
특히나 특정 도메인과 관련된 코드는 그 배경 지식과 관련해 주석문으로 설명하는 것이 좋다.

주석문에는 다음과 같은 내용이 들어가면 좋다.

• 코드가 무엇을 하는지
• 코드가 왜 그 일을 하는지
• 해당 코드의 사용 예,
• 추가적으로 함수라면 어떤 인자를 갖고, 어떤 값을 반환하는지도 서술하면 좋다.
• 책에서는 관련 이슈 번호를 작성했는데, pr 번호와 같이 관련 문서를 작성하는 것도 좋아보인다.

하지만 코드 뿐만 아니라 주석문 또한 유지보수 대상이 되는 점에서 책에서는 지양하라고 하는데, 개인적으로 필요한 부분에는 주석문이 꼭 필요하다고 느껴졌다.

TSDoc, JSDoc을 적극 사용하자. 👍
typedoc-plugin-markdown 메모...✏️

어느 곳에서 주석문을 활용해야 하는가?

다른 개발자가 알 수 없는 배경 지식을 작성해두면 좋다.

예를 들면,

• 비지니스 로직
• 도메인 지식

간결함에 집착하지 말기

같은 코드라도 간결하게 작성된 코드면 우선 멋있긴하다...! 하지만 간결한 코드는 가독성이 안좋기 마련이고 우리는 협업하기 좋은 동료로 성장하기 위해 간결함에 집착하지 말아야 한다.

간결함보다는 가독성을 추구하기..!

일관된 스타일 고수하기

팀이나 조직 전체가 같은 코딩 스타일을 따르면, 그것은 마치 모두가 같은 언어를 유창하게 말하는 것과 비슷하다.

깊이 중첩된 코드를 피해라

중첩은 하나의 함수에서 너무 많은 일을 처리한 결과이기도 하다. 그래서 최대한 early return pattern를 지향하는 편이다. else로 연결된 코드는 처음부터 모든 코드를 읽어햐하는 부담감이 따르기 때문이다.

가장 좋은 건 더 작은 함수로 분리해 추상화하는 것이 좋다.

르블랑의 법칙
한번 작성한 쓰레기 코드를 나중에 수정하는 일은 결코 없다.

함수 인자 개수

많은 매개변수를 가진 함수를 호출할 때 각 매개변수가 어떤 걸 의미하는지 분명하지 않기 때문에, 함수의 인자 개수는 최대 2개로 유지하고 2개 이상을 넘겨야 할 때는 차라리 객체로 넘겨주자.

잘 명명된 상수 사용하기

하드 코딩된 뜬금없는 값을 사용하기 보다 잘 명명된 상수를 사용해 값이 의미하는 바를 설명하는 것이 좋다.

익명 함수 적절히 사용하기

간단하고 자명한 곳에 익명 함수를 적절히 사용하면 코드의 가독성을 높여주지만, 복잡하거나 자명하지 않은 혹은 재사용해야 하는 것에 사용하면 문제가 될 수 있다.

아래 filter에 작성된 콜백 함수는 너무나 간단하고 쉽게 읽히기에 익명 함수를 작성하기에 적절하지만 만약 복잡한 조건을 표현해야 한다면 익명 함수로 작성하기 보다 명명 함수로 작성하는 것이 좋다. 익명 함수는 길면 문제가 되기 때문이다.

const getUser = (userId) => {
	return userList.filter(({ id }) => userId === id);
}