https://frontend-fundamentals.com/
토스에서 작성한 좋은 코드를 작성하기 위한 기준 및 전략들.
프론트엔드 코드를 중점으로 크게 가독성, 예측가능성, 응집도, 결합도라는 4가지 주제로 나누어 설명한다.
1. 가독성
읽기 좋은 코드는 읽는 사람이 한 번에 머릿속에서 고려하는 맥락이 적고, 위에서 아래로 자연스럽게 이어진다
맥락 줄이기
A. 같이 실행되지 않는 코드 분리하기
동시에 실행되지 않는 코드가 하나의 함수나 컴포넌트에 있으면 동작을 파악하기 어렵다.
코드 예시 아래 코드는 사용자의 권한에 따라 다르게 동작한다.
function SubmitButton() {
const isViewer = useRole() === "viewer";
useEffect(() => {
if (isViewer) {
return;
}
showButtonAnimation();
}, [isViewer]);
return isViewer ? (
<TextButton disabled>Submit</TextButton>
) : (
<Button type="submit">Submit</Button>
);
}코드스멜
권한에 따라 완전히 다른 동작을 하기에 같이 사용되지 않는 코드가 하나의 컴포넌트에 있어 동작을 한눈에 보기 어렵다
개선
관련된 코드를 묶어 코드를 읽는 사람이 고려해야할 맥락을 줄일 수 있다.
function SubmitButton() {
const isViewer = useRole() === "viewer";
return isViewer ? <ViewerSubmitButton /> : <AdminSubmitButton />;
}
function ViewerSubmitButton() {
return <TextButton disabled>Submit</TextButton>;
}
function AdminSubmitButton() {
useEffect(() => {
showAnimation();
}, []);
return <Button type="submit">Submit</Button>;
}B. 구현 상세 추상화하기
한 사람이 코드를 읽을 때 동시에 고려가능한 맥락의 수는 제한 되어있다. 따라서 불필요한 맥락을 추상화하여 코드의 가독성을 올릴 수 있다
코드 예시 1)
function LoginStartPage() {
useCheckLogin({
onChecked: (status) => {
if (status === "LOGGED_IN") {
location.href = "/home";
}
}
});
/* ... 로그인 관련 로직 ... */
return <>{/* ... 로그인 관련 컴포넌트 ... */}</>;
}코드 스멜
- LoginStartPage 의 내용을 읽기 전에 먼저 useCheckLogin의 동작을 파악해야함.
- 실제로 로그인과 관련된 코드는 밑에 있는데 그전에 파악해야할 맥락이 많음
개선
Wrapper 또는 HOC 패턴으로 useCheckLogin과 관련된 맥락을 분리할 수 있다
function App() {
return (
<AuthGuard>
<LoginStartPage />
</AuthGuard>
);
}
function AuthGuard({ children }) {
const status = useCheckLoginStatus();
useEffect(() => {
if (status === "LOGGED_IN") {
location.href = "/home";
}
}, [status]);
return status !== "LOGGED_IN" ? children : null;
}
function LoginStartPage() {
/* ... 로그인 관련 로직 ... */
return <>{/* ... 로그인 관련 컴포넌트 ... */}</>;
}코드 예시 2)
function FriendInvitation() {
const { data } = useQuery(/* 생략.. */);
// 이외 이 컴포넌트에 필요한 상태 관리, 이벤트 핸들러 및 비동기 작업 로직...
const handleClick = async () => {
const canInvite = await overlay.openAsync(({ isOpen, close }) => (
<ConfirmDialog
title={`${data.name}님에게 공유해요`}
cancelButton={
<ConfirmDialog.CancelButton onClick={() => close(false)}>
닫기
</ConfirmDialog.CancelButton>
}
confirmButton={
<ConfirmDialog.ConfirmButton onClick={() => close(true)}>
확인
</ConfirmDialog.ConfirmButton>
}
/* 중략 */
/>
));
if (canInvite) {
await sendPush();
}
};
// 이외 이 컴포넌트에 필요한 상태 관리, 이벤트 핸들러 및 비동기 작업 로직...
return (
<>
<Button onClick={handleClick}>초대하기</Button>
{/* UI를 위한 JSX 마크업... */}
</>
);
}코드스멜
FriendInvitation안에 사용자에게 동의를 받는 구체적인 로직이 같이 포함되어 있어 한번에 맥락을 파악하기 힘듦- hadnelClick과 이 함수가 부착되는 위치가 멀리 떨어져이어 응집도가 떨어짐
개선
동의를 받는 로직과 버튼을 한데로 묶어 <InviteButton/> 로 추상화 할 수 있다
export function FriendInvitation() {
const { data } = useQuery(/* 생략.. */);
// 이외 이 컴포넌트에 필요한 상태 관리, 이벤트 핸들러 및 비동기 작업 로직...
return (
<>
<InviteButton name={data.name} />
{/* UI를 위한 JSX 마크업 */}
</>
);
}
function InviteButton({ name }) {
return (
<Button
onClick={async () => {
const canInvite = await overlay.openAsync(({ isOpen, close }) => (
<ConfirmDialog
title={`${name}님에게 공유해요`}
cancelButton={
<ConfirmDialog.CancelButton onClick={() => close(false)}>
닫기
</ConfirmDialog.CancelButton>
}
confirmButton={
<ConfirmDialog.ConfirmButton onClick={() => close(true)}>
확인
</ConfirmDialog.ConfirmButton>
}
/* 중략 */
/>
));
if (canInvite) {
await sendPush();
}
}}
>
초대하기
</Button>
);
}더 알아보기: 추상화
선언적인 코드 작성하기 의 예시로 추상화를 비유할 수 있다
글에서의 추상화 : “왼쪽으로 10걸음 걸어라”
- 왼쪽은 북쪽을 바라보았을때 90도 돌아간 위치
- 한 걸음 당 1m
- 걷는다는 것은 신체가 그 방향으로 움직인다는 것
코드에서의 추상화
- 비슷한 로직을 한데로 묶어 그 코드를 사용하는 쪽에서는 인터페이스만 보고 동작을 이해할 수 있도록 하기
C. 로직 종류에 따라 합쳐진 함수 쪼개기
쿼리 파라미터, 상태, API 호출을 모두 담당하는 함수나 컴포넌트, Hook을 만들 경우 한번에 다루는 맥락이 너무 많아져서 이해하기 힘들어질 수 있다
코드예시
import moment, { Moment } from "moment";
import { useMemo } from "react";
import {
DateParam,
NumberParam,
useQueryParams
} from "use-query-params";
const defaultDateFrom = moment().subtract(3, "month");
const defaultDateTo = moment();
export function usePageState() {
const [query, setQuery] = useQueryParams({
cardId: NumberParam,
dateFrom: DateParam,
dateTo: DateParam,
});
return useMemo(
() => ({
values: {
cardId: query.cardId ?? undefined,
dateFrom:
query.dateFrom == null ? defaultDateFrom : moment(query.dateFrom),
dateTo: query.dateTo == null ? defaultDateTo : moment(query.dateTo)
},
controls: {
setCardId: (cardId: number) => setQuery({ cardId }, "replaceIn"),
setDateFrom: (date?: Moment) =>
setQuery({ dateFrom: date?.toDate() }, "replaceIn"),
setDateTo: (date?: Moment) =>
setQuery({ dateTo: date?.toDate() }, "replaceIn")
}
}),
[query, setQuery]
);
}코드 스멜
- 가독성 : 페이지에서 관리하는 모든 쿼리 파라미터를 관리하다보니 Hook의 책임이 무한하게 늘어날 수 있다. 따라서 새로운 파라미터가 추가될때마다 맥락이 추가되고, 이는 가독성의 하락으로 이어진다
- 성능 : 한 쿼리파라미터만 변경되어도 이 hook을 사용하는 모든 컴포넌트에서 리렌더링이 발생한다.
개선
각각의 쿼리 파라미터 별로 따로 관리할 수 있다.
import { NumberParam, useQueryParam } from "use-query-params";
export function useCardIdQueryParam() {
const [cardId, _setCardId] = useQueryParam("cardId", NumberParam);
const setCardId = useCallback((cardId: number) => {
_setCardId({ cardId }, "replaceIn");
}, []);
return [cardId ?? undefined, setCardId] as const;
}이름 붙이기
A. 복잡한 조건에 이름붙이기
복잡한 조건식이 특별한 이름없이 사용되면 조건이 뜻하는 바를 한눈에 파악하기 어렵다
코드 예시
const result = products.filter((product) =>
product.categories.some(
(category) =>
category.id === targetCategory.id &&
product.prices.some(
(price) => price >= minPrice && price <= maxPrice
)
)
);코드스멜
- filter, some, && 과 같은 로직이 여러 단계로 중첩되어 있어 정확한 조건을 파악하기 어렵다.
개선 결과값, 각 조건마다 이름을 붙여 고려해야할 한번에 맥락을 줄일 수 있다.
const matchedProducts = products.filter((product) => {
return product.categories.some((category) => {
const isSameCategory = category.id === targetCategory.id;
const isPriceInRange = product.prices.some(
(price) => price >= minPrice && price <= maxPrice
);
return isSameCategory && isPriceInRange;
});
});더 알아보기 : 조건식에 이름을 붙이는 기준
조건에 이름을 붙이는 것이 좋을때
- 복잡한 로직을 다룰때 : 복잡한 로직이 몇줄에 걸쳐 진행되면 이름을 붙여 함수의 역할을 드러내는 것이 좋다
- 재사용성이 필요할 때 : 동일한 로직을 여러 곳에서 반복적으로 사용할 경우, 변수나 함수를 선언해 재사용가능하다
- 단위 테스트가 필요할때
조건에 이름을 붙이지 않아도 괜찮을때
- 로직이 간단할때 (ex :
arr.map(x => x * 2)) - 한번만 사용될 때
B. 매직 넘버에 이름붙이기
코드 예시
async function onLikeClick() {
await postLike(url);
await delay(300); // 매직넘버 사용
await refetchPostLike();
}코드스멜 원래 개발자가 아니라면 왜 300을 가다리는지, 300이 ms인지 s인지 모른다. 어떤 의도에서 사용되었는지 모르기에 다른 개발자가 섣불리 건들기 어려운 코드가 된다
개선 매직넘버에 적절한 이름을 붙여 해당 값의 의도를 파악할 수 있도록 할 수 있다.
const ANIMATION_DELAY_MS = 300;
async function onLikeClick() {
await postLike(url);
await delay(ANIMATION_DELAY_MS);
await refetchPostLike();
}위에서 아래로 읽게 하기
A. 시점 이동 줄이기
코드를 읽을 때, 위아래를 왔다갔다 하면서 읽거나, 여러 파일이나 함수, 변수를 넘나드면서 읽는 것을 시점 이동이라한다. 이러한 시점이동이 적어야 코드를 파악하기 쉽다
코드 예시
function Page() {
const user = useUser();
const policy = getPolicyByRole(user.role);
return (
<div>
<Button disabled={!policy.canInvite}>Invite</Button>
<Button disabled={!policy.canView}>View</Button>
</div>
);
}
function getPolicyByRole(role) {
const policy = POLICY_SET[role];
return {
canInvite: policy.includes("invite"),
canView: policy.includes("view")
};
}
const POLICY_SET = {
admin: ["invite", "view"],
viewer: ["view"]
};코드스멜
Invite버튼이 비활성화된 이유를 찾기 위해서는policy.canInvite→getPolicyByRole→POLICY_SET을 넘나드며 읽어야한다- 이러한 추상화는 권한 체계가 복잡할 경우에는 유용하지만, 지금처럼 간단한 경우에는 시점이동을 많게만 할 뿐이다
개선
- 조건을 펼쳐서 그대로 보여주기
function Page() {
const user = useUser();
switch (user.role) {
case "admin":
return (
<div>
<Button disabled={false}>Invite</Button>
<Button disabled={false}>View</Button>
</div>
);
case "viewer":
return (
<div>
<Button disabled={true}>Invite</Button>
<Button disabled={false}>View</Button>
</div>
);
default:
return null;
}
}- 조건을 한눈에 볼 수 있는 객체로 만들기
function Page() {
const user = useUser();
const policy = {
admin: { canInvite: true, canView: true },
viewer: { canInvite: false, canView: true }
}[user.role];
return (
<div>
<Button disabled={!policy.canInvite}>Invite</Button>
<Button disabled={!policy.canView}>View</Button>
</div>
);
}B. 삼항 연산자 단순하게 하기
삼항 연산자가 복잡하면 조건의 구조를 파악하기 어렵다
코드 예시
const status =
(A조건 && B조건) ? "BOTH" : (A조건 || B조건) ? (A조건 ? "A" : "B") : "NONE";개선
const status = (() => {
if (A조건 && B조건) return "BOTH";
if (A조건) return "A";
if (B조건) return "B";
return "NONE";
})();2. 예측 가능성
함께 협업하는 동료들이 함수나 컴포넌트의 동작을 얼마나 잘 예측할 수 있는지.
예측가능성이 높은 코드는 일관적인 규칙을 따르고, 함수나 컴포넌트의 이름/파라미터/반환갑만 보고도 동작을 알 수 있다.
A. 이름 겹치지 않게 관리하기
같은 이름을 가지면 동일한 동작을 해야한다. 작은 동작 차이가 코드의 예측가능성을 낮추고 코드를 읽는 사람으로 하여금 혼란을 줄 수 있다
코드 예시
// 이 서비스는 `http`라는 라이브러리를 쓰고 있어요
import { http as httpLibrary } from "@some-library/http";
export const http = {
async get(url: string) {
const token = await fetchToken();
return httpLibrary.get(url, {
headers: { Authorization: `Bearer ${token}` }
});
}
};코드스멜
http.get이라는 이름은 단순히 get 요청을 날리는 것이라고 예측하기 쉬움. 하지만 실제로는 토큰을 가져와 함께 넣어주는 작업을 포함함
개선
- 이름을 변경하여 추가적인 작업이 있다고 에측가능하게 할 수 있음.
// 이 서비스는 `http`라는 라이브러리를 쓰고 있어요
import { http as httpLibrary } from "@some-library/http";
// 라이브러리 함수명과 구분되도록 명칭을 변경했어요.
export const httpService = {
async getWithAuth(url: string) {
const token = await fetchToken();
// 토큰을 헤더에 추가하는 등 인증 로직을 추가해요.
return httpLibrary.get(url, {
headers: { Authorization: `Bearer ${token}` }
});
}
};B. 같은 종류의 함수는 반환 타입 통일하기
API 호출과 관련된 Hook 들 처럼 같은 종류의 함수나 Hook이 서로 다른 반환 타입을 가지면 코드의 일관성이 떨어진다.
example 1. useUser
코드예시
import { useQuery } from '@tanstack/react-query';
function useUser() {
const query = useQuery({
queryKey: ['user'],
queryFn: fetchUser
});
return query;
}
function useServerTime() {
const query = useQuery({
queryKey: ['serverTime'],
queryFn: fetchServerTime
});
return query.data;
}코드 스멜
useUser와useServerTime의 반환값이 다르기에, 이 훅들을 사용할때 해당 훅의 반환값이 무엇인지 확인해서,query면 data를 뽑아야하고,query.data면 그대로 사용해야한다.- 이러한 불규칙성은 예측 가능성을 저하시킨다
개선
- 일관적으로
query객체를 반환하도록 수정하면 예측하기 더 쉬워진다
example 2. checkValid
코드 예시
/** 사용자 이름은 20자 미만이어야 해요. */
function checkIsNameValid(name: string) {
const isValid = name.length > 0 && name.length < 20;
return isValid;
}
/** 사용자 나이는 18세 이상 99세 이하의 자연수여야 해요. */
function checkIsAgeValid(age: number) {
if (!Number.isInteger(age)) {
return {
ok: false,
reason: "나이는 정수여야 해요."
};
}
if (age < 18) {
return {
ok: false,
reason: "나이는 18세 이상이어야 해요."
};
}
if (age > 99) {
return {
ok: false,
reason: "나이는 99세 이하이어야 해요."
};
}
return { ok: true };
}코드 스멜
- 같은 종류의
checkIs함수이나 반환값이 서로 달라 함수를 쓸때마다 반환 타입을 확인해야한다. - 가장 중요한 기능인 valid 여부를 확인 하는 방법이 함수마다 다르다,
개선
{ok, ...}과 같이 결과를 확인하는 동작이 동일하게 이루어질 수 있도록 동일한 타입의 객체를 반환하도록 수정할 수 있다.- 아래처럼 ts를 활용해
ok:false일때만 reason이 들어가도록 할수 있다
type ValidationCheckReturnType = { ok: true } | { ok: false; reason: string };C. 숨은 로직 드러내기
함수나 컴포넌트의 이름, 파라미터, 반환값이 드러나지 않은 로직이 있다면 동작을 예측하기 어려워진다
코드 예시
async function fetchBalance(): Promise<number> {
const balance = await http.get<number>("...");
logging.log("balance_fetched");
return balance;
}코드스멜
- 함수를 호출할 때마다
balance_fetched라는 로깅을 하고 있는데, 이 동작을 함수 이름과 반환 타입만으로 예측하기 어렵다. - 따라서 로깅을 원하지 않을 때에도 로깅이 발생할 수 있으며, 로깅 로직에 에러가 발생했을 경우 해당 함수 자체가 동작하지 않게 된다.
개선 예측 가능한 부분만 남기고, 로깅하는 부분은 따로 분리하라
async function fetchBalance(): Promise<number> {
const balance = await http.get<number>("...");
return balance;
}<Button
onClick={async () => {
const balance = await fetchBalance();
logging.log("balance_fetched");
await syncBalance(balance);
}}
>
계좌 잔액 갱신하기
</Button>3. 응집도
수정되어야할 코드가 같이 붙어있는지.
응집도가 높으면 코드의 한 부분을 수정해도 의도치 않게 다른 부분에서 오류가 발생할 가능성이 적어진다. 항상 반드시 같이 수정되도록 구조적으로 뒷받침되기 때문이다.
응집도와 가독성은 서로 상충할 수 있다
일반적으로 응집도를 높이려면 변수나 함수를 추상화하여 가독성을 떨어트려야한다. 함께 수정되지 않으면 오류가 발생할 경우엔 응집도를 우선해서 코드를 공통화, 추상화해야한다. 위험성이 높지 않으면 가독성을 우선하여 코드 중복을 허용할 수 있다
4. 결합도
코드를 수정했을 때의 영향범위. 코드 수정 시 영향범위가 적어서 변경에 따른 범위를 예측할 수 있는 코드가 수정하기 쉬운 코드이다.