클린 코드 팁: 모든 댓글이 나쁜 것은 아닙니다.

많은 개발자들이 말합니다.

All comments are bad! 💢

거짓! 악플이 대부분!

나쁜 댓글의 예

예를 들어, 이 메서드를 살펴보고 주석을 살펴보세요.

/// <summary> Checks if the password is valid </summary>
/// <param name="password">The password to be validated</param>
/// <returns>True if the password is valid, false otherwise</returns>
public bool IsPasswordValid(string password)
{
    Regex regex = new Regex(@"[a-z]{2,7}[1-9]{3,4}");
    var hasMatch = regex.IsMatch(password);
    return hasMatch;
}

여기서 주석은 의미가 없습니다. 메서드 서명을 보고 추론할 수 있는 것과 동일한 내용을 알려줍니다. 이 메서드는 입력 문자열이 유효한 암호인지 확인합니다.

네, 그런 종류의 댓글은 완전히 무의미하며 피해야 합니다.

좋은 댓글 유형

하지만 그래도 댓글을 작성하는 것이 꽤 도움이 되는 경우가 있습니다.

public bool IsPasswordValid(string password)
{
    // 2 to 7 lowercase chars followed by 3 or 4 numbers
    // Valid:   kejix173
    //          aoe193
    // Invalid: a92881
    Regex regex = new Regex(@"[a-z]{2,7}[1-9]{3,4}");
    return regex.IsMatch(password);
}

여기서 주석의 목적은 메서드가 수행하는 작업을 설명하는 것이 아니라(이미 매우 명시적임) 암호를 확인하는 데 사용되는 정규식을 예제로 설명합니다. 이를 설명하는 또 다른 방법은 일부 입력 문자열의 유효성을 검사하는 테스트를 추가하는 것입니다. 이러한 방식으로 문서(일명 테스트)가 항상 프로덕션 코드와 일치하는지 확인합니다.

그런데 더 복잡한 계산을 위해 코드 조각이 WHY(어떻게 또는 무엇을 하는 것이 아니라)를 설명하는 주석을 추가하는 것은 개발자가 코드를 이해하는 데 도움이 되는 좋은 방법입니다.

주석을 추가하는 또 다른 이유는 특정 코드 조각이 존재하는 이유를 설명하기 위한 것입니다. 예를 들면 법적 규정, 관련 작업 항목 또는 특정 솔루션을 찾은 위치에 대한 참조입니다.

결론

주석을 작성할 때는 항상 주의를 기울이십시오. 예, 주석은 종종 코드를 어지럽힐 뿐입니다. 그러나 경우에 따라 코드에 실제로 가치를 추가할 수 있습니다.

좋은 댓글과 나쁜 댓글에 대해 자세히 알아보려면 다음과 같은 자세한 기사를 참조하세요.

🔗 Clean code tips - comments and formatting

즐거운 코딩하세요!

🐧