상사처럼 코드를 주석 처리하는 방법

댓글은 마늘과 같습니다.

접시를 위로 밀어 올릴 수 있습니다. 또는 손님이 감사하지만 즐기지 않은 정중한 남은 음식 더미로 분류할 수 있습니다.

코드의 주석은 거의 동일합니다. 훌륭하고 명확하며 필요한 주석은 코드의 복잡한 설명을 명확하고 따라하기 쉬운 이야기로 유지하는 데 도움이 될 수 있습니다.

코드 섹션에 주석이 필요한지 또는 맨손으로 남겨야 하는지 결정할 때 도움이 된 두 가지 주요 아이디어는 다음과 같습니다.

💡 코드는 무슨 일이 일어나고 있는지 설명해야 합니다.

Uncle Bob's Clean Code의 진정한 보석은 명명에 관한 장입니다. 명확하고 명확한 이름 지정은 코드를 명확하고 따르기 쉽게 만드는 데 도움이 됩니다.

대신:

// get the length of an array
const gl = a => a.length

우리는 이것을 씁니다:

const getArrayLength = a => a.length

이를 통해 표현력이 뛰어난 코드를 작성할 수 있습니다. 코드 자체가 무슨 일이 일어나고 있는지 알려줍니다. 위의 간단한 예에서 함수의 이름은 그 역할을 알려줍니다. 위의 주석에서 이것을 앵무새로 만들 필요는 없습니다. 주석을 작성할 때마다 코드뿐만 아니라 주석도 구문 분석해야 하는 정신적 오버헤드가 추가됩니다. 이것이 댓글이 제한적이고 의미가 있어야 하는 이유입니다.

💡 댓글은 이유를 설명해야 합니다.

두 데이터베이스 간에 분할된 사용자 기반이 있다고 가정해 보겠습니다. 클라이언트 또는 제품에는 이전 시스템, 새 시스템의 사용자가 있으며 우리의 애플리케이션은 코드 기반을 새 플랫폼으로 전환하는 동안 두 가지 모두를 관리해야 합니다.

import oldsdk from 'old-sdk';
import newsdk from 'new-sdk';

const getUserByEmail = async email => {

    // we switched identity providers
    // and not all users are migrated yet.
    const oldUserData = await oldsdk.getUserByEmail(email);
    const newUserData = await newsdk.getUserByEmail(email);
    return newUserData || oldUserData;
}

이 예에서는 새 SDK와 이전 SDK를 사용하여 일부 API에서 사용자를 가져옵니다. 이런 일은 항상 발생합니다. 이 코드를 읽는 누군가에게는 변수 이름이 설명적이지만 왜 이런 일이 일어나는지 모릅니다. 이 코드의 주석은 이 코드의 목적을 설명합니다. 아직 명확한 것.

결론

많은 것들과 마찬가지로 이것은 어렵고 빠른 규칙이 아닙니다. 사실, 그것은 규칙이 아니라 도구에 가깝습니다. 좋은 논평을 쓰기 위한 바로미터로서 제 경력에 도움이 된 일반화된 이정표입니다. 다르게 접근하기를 원하거나 접근해야 하는 상황이 많이 있지만 이 팁은 댓글 작성에 대한 감을 잡을 때 좋은 출발점이 될 수 있습니다.

즐거운 코딩!