소개

bob 아저씨에 따르면 댓글은 어떤 대가를 치르더라도 피해야 합니다. 잘 작성된 코드는 다른 개발자가 이해하기 쉬운 방식으로 작성되어야 합니다. 주석을 피하는 데 설명된 대로 개발자가 깨끗한 메서드 작성 규칙을 따른다면 훨씬 더 의미가 있습니다.

코드 설명

개발자는 때때로 논리를 작성하고 주석을 통해 코드를 설명하려고 합니다. 대부분의 경우 이러한 주석은 아래 코드에 표시된 것처럼 필요하지 않습니다.

// Verify if user has access to every module.
if ((user.Type == ADMINISTRATOR || user.Type == MANAGER) && 
     user.IsActive) { }

if (user.HasAccessToWholeModule) { }

두 경우 모두 위의 코드는 동일한 책임이 있습니다. 두 번째 경우는 목적을 설명하기 위해 주석이 필요하지 않은 훨씬 더 깔끔한 접근 방식입니다. 코드가 발전함에 따라 프로그래머가 주석을 업데이트하지 않으면 주석도 쓸모없게 될 수 있습니다.

유용한 댓글

경우에 따라 주석을 작성하는 것이 유용할 수 있지만 주석이 없는 것이 주석이 있는 것보다 항상 낫다는 점을 명심하는 것이 중요합니다. 다음 코드를 분석합니다.

services.AddQuartz(q =>
{
q.UseMicrosoftDependencyInjectionScopedJobFactory();
var jobKey = new JobKey(JOB_NAME);

q.AddJob<HelloWorldJob>(opts => opts.WithIdentity(jobKey));

q.AddTrigger(opts => 
  opts.ForJob(jobKey) 
      .WithIdentity(JOB_TRIGGER_NAME)
      .WithCronSchedule("0/5 * * * * ?")); // run every 5 seconds
});

위의 코드는 quartz이라는 오픈 소스 작업 스케줄링 시스템 라이브러리의 미들웨어 구성 예입니다. cron을 사용하여 일정을 정의하고 이 경우 일정을 해석하기 위해 주석을 추가하는 것이 좋습니다.

다음과 같은 코드에서 다른 주석도 적절할 수 있습니다.

중요한 기능

메서드에 대해 사용되지 않거나 보류 중인 항목을 설명하는 TODO.

장기 실행 프로세스에 대해 경고합니다.

과도한 댓글

과도한 주석이 있는 코드에 자주 부딪칩니다. 프로그래머는 이러한 주석이 있는 코드가 우아해 보인다고 생각할 수 있지만 중복되고 필요하지 않습니다. 아래 코드에는 과도한 주석의 예가 있습니다.

/// <summary>
/// User Class
/// </summary>
public class User
{
    /// <summary>
    /// User Type
    /// </summary>
    public string Type { get; set; }

    /// <summary>
    /// Verifies if user is active
    /// </summary>
    public bool IsActive { get; set; }
}

지역

C#의 영역은 때때로 "코드 가독성 향상"을 위해 메서드 내에서 사용됩니다. 메서드 내부의 영역은 실제로 메서드의 크기를 증가시키므로 어떤 희생을 치르더라도 피해야 합니다. 코드를 구성하기 위해 메서드 외부에서 영역을 사용할 수 있지만 이 역시 피해야 합니다. 클래스에 수백 또는 수천 줄의 코드가 포함된 일부 경우에는 다음 그림과 같이 영역을 갖는 것이 합리적일 수 있습니다.

결론

여기에서 살펴보지 않고 피해야 하는 주석의 다른 많은 예가 있습니다. 이 시점에 이르렀을 때 알아야 할 주요 아이디어는 가능할 때마다 항상 코드에 주석을 달지 않는 것입니다. 시스템, 요구 사항 및 아키텍처에 대한 간결한 외부 문서가 있으면 코드에서 많은 불필요한 주석을 피할 수 있습니다.

참조

클린 코드: Robert C. Martin의 애자일 소프트웨어 장인 정신 핸드북.

Quartz