주석 처리 된 코드가 유용한 문서가 될 수 있습니까?

다음 코드를 작성했습니다.

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

여기에 주석 처리 된 행이 있습니다. 그러나 if와 의 차이점을 분명히함으로써 코드를 명확하게 만든다고 생각합니다 else. 차이점은 색상 강조 표시에서 더욱 두드러집니다.

이와 같은 코드를 주석 처리하는 것이 좋은 아이디어가 될 수 있습니까?

대부분의 답변은이 특정 사례를 리팩토링하는 방법에 중점을두고 있지만 주석 처리 된 코드가 일반적으로 나쁜 이유에 대한 일반적인 답변을 제공하겠습니다.

먼저 주석 처리 된 코드가 컴파일되지 않습니다. 이것은 분명하지만 다음을 의미합니다.

1. 코드가 작동하지 않을 수도 있습니다.

2. 주석의 종속성이 변경 될 때 분명히 중단되지 않습니다.

주석이 달린 코드는 매우 "죽은 코드"입니다. 오래 앉아있을수록 더 많이 썩고 다음 개발자에게 더 적은 가치를 제공합니다.

둘째, 목적이 불분명하다. 무작위로 주석 처리 된 행이있는 이유에 대한 컨텍스트를 제공하는 더 긴 주석이 필요합니다. 주석 처리 된 코드 줄을 볼 때 왜 그것이 도착했는지 이해하기 위해 그것이 어떻게 도착했는지 연구해야합니다. 누가 썼니? 무슨 일이야? 커밋 메시지 / 컨텍스트는 무엇입니까? 기타.

대안을 고려하십시오.

• 목표가 함수 / api를 사용하는 예제를 제공하는 경우 단위 테스트를 제공하십시오. 단위 테스트는 실제 코드이며 더 이상 정확하지 않으면 중단됩니다.
• 이전 버전의 코드를 유지하려는 목적이라면 소스 제어를 사용하십시오. 이전 버전을 체크 아웃 한 다음 코드베이스 전체에서 주석을 토글하여 변경 사항을 "되 돌리십시오".
• 동일한 코드 의 대체 버전 을 유지하려는 경우 소스 제어를 다시 사용하십시오. 이것이 바로 가지입니다.
• 구조를 명확하게하는 것이 목적이라면, 코드를보다 명확하게 만들기 위해 코드를 재구성하는 방법을 고려하십시오. 다른 답변의 대부분은이 작업을 수행하는 방법에 대한 좋은 예입니다.

이 코드의 가장 큰 문제는 6 줄을 복제 한 것입니다. 중복을 제거하면 해당 주석은 쓸모가 없습니다.

당신이 작성하는 경우 boutiqueDao.mergeOrPersist방법이를 같이 다시 작성할 수 있습니다 :

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

특정 객체를 만들거나 업데이트하는 코드는 일반적이므로 mergeOrPersist메소드 를 작성하여 한 번만 해결해야합니다 . 이 두 경우의 할당 코드를 모두 복제해서는 안됩니다.

많은 ORM이 어떤 방식 으로든이를 지원합니다. 예를 들어, id가 0 이면 새 행을 만들고 0이 아닌 경우 기존 행을 업데이트 할 수 id있습니다. 정확한 형식은 해당 ORM에 따라 다르며 사용중인 기술에 익숙하지 않으므로 도움을 드릴 수 없습니다.

mergeOrPersist메소드 를 작성하지 않으려면 isNewBoutique플래그 를 도입하는 등 다른 방법으로 중복을 제거해야합니다 . 예쁘지는 않지만 전체 할당 논리를 복제하는 것보다 훨씬 낫습니다.

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

이것은 절대적으로 끔찍한 생각입니다. 의도가 무엇인지 명확하지 않습니다. 개발자가 실수로 라인을 주석 처리 했습니까? 무언가를 테스트하려면? 무슨 일이야?!

두 경우 모두에서 절대적으로 동일한 6 줄을 볼 수 있습니다. 오히려이 코드 복제를 방지해야합니다. 어떤 경우에는 setSelected를 추가로 호출하는 것이 더 명확합니다.

아니요, 끔찍한 생각입니다. 이 코드를 기반으로 다음 생각이 떠 오릅니다.

• 이 줄은 개발자가 디버깅했기 때문에 주석 처리되었으며 해당 줄을 이전 상태로 복원하는 것을 잊었습니다.
• 이 줄은 한 번 비즈니스 논리의 일부 였기 때문에 주석 처리되었지만 더 이상 그렇지 않습니다.
• 이 라인은 프로덕션에서 성능 문제를 일으켰으며 개발자가 프로덕션 시스템에 미치는 영향을 확인하려고했기 때문에 주석 처리되었습니다.

수천 줄의 주석 처리 된 코드를 본 후 나는 그것을 볼 때 현명한 일을하고 있습니다. 즉시 제거합니다.

주석 처리 된 코드를 리포지토리에 체크인해야 할 합리적인 이유는 없습니다.

또한 코드는 많은 중복을 사용합니다. 가능한 빨리 인간의 가독성을 위해 최적화하십시오.

작은 메소드로 리팩토링 할 수 있음을 지적함으로써 코드 인 카오스의 답변에 추가하고 싶습니다 . 컴포지션별로 공통 기능을 공유하면 조건을 피할 수 있습니다.

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

이것은 주석 처리 된 코드에는 분명히 좋은 사례는 아니지만 보증해야 할 상황이 있습니다.

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

나중에 눈에 띄게 개선되지 않은 것을 보는 사람에게는 경고입니다.

편집 : 나는 작은 것에 대해 이야기하고 있습니다. 큰 경우 대신 설명하십시오.

이 특정 예제에서는 Dibkke의 답변에 설명 된 이유로 주석 처리 된 코드가 매우 모호합니다 . 다른 사람들은 코드를 리팩터링하여 유혹을 피할 수있는 방법을 제안했지만 어떤 이유로 든 불가능한 경우 (예 : 선이 비슷하지만 충분히 가깝지 않은 경우) 다음과 같은 의견을 부탁드립니다.

//이 부티크를 선택 해제 할 필요가 없습니다. [WHATEVER]

그러나 코드를 남기거나 주석 처리 한 코드를 이해할 수없는 상황이 있다고 생각합니다. MATLAB 또는 NumPY와 같은 것을 사용할 때 종종 1) 배열을 반복하고 한 번에 하나의 요소를 처리하거나 2) 전체 배열을 한 번에 운영하는 동등한 코드를 작성할 수 있습니다. 어떤 경우에는 후자가 훨씬 빠르지 만 읽기가 훨씬 어렵습니다. 일부 코드를 벡터화 된 해당 코드로 바꾸면 다음과 같이 원본 코드를 근처 주석에 포함시킵니다.

%% 아래의 벡터화 된 코드는 다음을 수행합니다.

% for ii in 1:N
%    for jj in 1:N
%      etc.

%이지만 매트릭스 버전은 일반 입력에서 ~ 15 배 더 빠릅니다 (MK, 03/10/2013)

분명히, 두 버전이 실제로 동일한 작업을 수행하고 주석이 실제 코드와 동기화 상태를 유지하거나 코드가 변경되면 제거되도록주의해야합니다. 분명히 조기 최적화에 대한 일반적인주의 사항도 적용됩니다 ...

유용한 주석 처리 된 코드를 보았던 유일한 시간은 모든 옵션에 대한 코드가 제공되지만 주석 처리 된 구성 파일에서만 주석 표시를 제거하여 설정을 쉽게 활성화 할 수있었습니다.

## Enable support for mouse input:
# enable_mouse = true

이 경우 주석 처리 된 코드는 사용 가능한 모든 옵션과 사용 방법을 문서화하는 데 도움이됩니다. 기본적으로 전체 기본값을 사용하는 것이 일반적이므로 코드도 기본 설정을 문서화합니다.

일반적으로 코드는 코드를 작성한 사람에게만 자체 문서화됩니다. 문서가 필요한 경우 문서를 작성하십시오. 소스 코드 기반의 새로운 개발자가 수천 줄의 코드를 읽음으로써 일어나고있는 일을 고수준에서 파악하려고 할 것으로 기대할 수 없습니다.

이 경우 주석 처리 된 코드 라인의 목적은 중복 코드의 두 인스턴스 간 차이를 표시하는 것입니다. 주석으로 차이점을 미묘하게 문서화하려고 시도하는 대신 코드를 다시 작성하여 이해하십시오. 그런 다음 여전히 코드에 주석을 달아야한다고 생각되면 적절한 주석을 작성하십시오.

아니요, 주석이 달린 코드는 오래되고 가치가없는 것보다 더 나빠집니다. 현재의 모든 가정과 함께 구현의 일부 측면을 통합하기 때문에 종종 유해합니다.

의견은 인터페이스 세부 사항과 의도 된 기능을 포함해야한다. "의도 된 기능": 먼저 시도해 본 다음 시도하면 실패합니다.

내가 본 프로그래머들은 의견을 남기려고 노력했지만 완성 된 제품에 아무것도 추가하지 않더라도 잃어버린 것을 원하지 않습니다.

매우 드문 경우 일 수 있지만 수행 한 것은 아닙니다. 다른 답변은 그 이유를 잘 알고 있습니다.

드문 경우 중 하나는 상점에서 모든 새 패키지의 시작점으로 사용 하는 템플릿 RPM 사양 이며, 중요한 것은 무엇이든 배제하지 않습니다. 대부분의 패키지는 표준 이름을 가지며 태그로 지정된 소스를 포함하는 tarball을 가지고 있습니다.

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

소스가없는 패키지의 경우 표준 형식을 유지하기 위해 태그를 주석 처리하고 그 위에 주석을 추가하여 누군가 개발 프로세스의 일부로 문제를 중지하고 생각했음을 나타냅니다.

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

다른 사람들이 다루었 듯이 거기에 속하는 것으로 잘못 판단 될 수 있기 때문에 사용하지 않을 코드를 추가하지 마십시오. 할 수 있습니다. 그러나 코드가 누락 될 것으로 예상되는 이유를 설명하는 주석을 추가하는 것이 유용합니다.

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

주석 처리 된 코드는 응용 프로그램에서 사용되지 않으므로 코드를 사용하지 않는 이유를 설명하는 추가 주석이 동반되어야 합니다. 하지만 그 맥락에서, 거기에 있는 주석 처리 된 코드가 도움이 될 수있는 상황은.

내 마음에 오는 것은 공통적이고 매력적인 접근 방식을 사용하여 문제를 해결하는 경우이지만 실제 문제의 요구 사항은 해당 문제와 약간 다릅니다. 특히 요구 사항이 훨씬 더 많은 코드를 요구하는 것으로 판명되면 유지 관리 담당자가 이전 방식을 사용하여 코드를 "최적화"하려는 유혹이 강할 수 있지만 그렇게하면 버그가 다시 발생합니다. 주석에서 "잘못된"구현을 유지하면 이 상황 을 해소하는 데 도움이 될 것 입니다.이 상황에서 이러한 접근 방식이 왜 잘못되었는지 정확하게 설명 할 수 있기 때문 입니다.

이것은 내가 자주 발생한다고 상상할 수있는 상황이 아닙니다. 일반적으로 샘플 "잘못된"구현을 포함하지 않고 내용을 설명하는 것으로 충분합니다. 그러나 나는 그것이 충분하지 않은 경우 를 상상할 수 있습니다 . 그래서 그것이 유용 할 수 있는지에 대한 질문이기 때문에 가능합니다. 대부분의 시간이 아닙니다.

이것은 좋은 친구처럼 보이지 않습니다.

주석 처리 된 코드는 ... 코드가 아닙니다. 코드는 논리 구현을위한 것입니다. 코드 자체를 더 읽기 쉽게 만드는 것은 예술입니다. @CodesInChaos는 이미 반복적 인 코드 라인이 로직 구현에 적합하지 않다고 제안했다 .

진정한 프로그래머가 논리적 구현보다 가독성을 선호한다고 생각하십니까? (논리적으로 우리는 논리적 인 표현에 의견과 '보완'을가집니다).

내가 아는 한, 컴파일러 용 코드를 작성해야하며 그 코드를 이해한다면 좋습니다. 사람이 쉽게 읽을 수 있도록 주석은 개발자 (장기적으로)에게 해당 코드를 재사용하는 사람들 (예 : 테스터)에게 좋습니다.

그렇지 않으면 여기보다 유연한 것을 시도해 볼 수 있습니다.

boutique.setSite (site)로 교체 가능

setsiteof.boutique (사이트). 가독성을 높일 수있는 OOP에는 여러 가지 측면과 관점이 있습니다.

이 코드는 처음에는 매우 호소력이 있고 사람이 읽을 수있는 방법을 찾았지만 컴파일러는 작업을 완벽하게 수행한다고 생각할 수 있지만 우리는이 연습을 시작하여 퍼지 파일을 읽을 수 없게됩니다. 시간이 지날수록 더 복잡해집니다.