주석 제거

에 게시한 후 대부분의 토론이 코드 주석에 집중되어 있음을 발견했습니다. 구체적으로 보이스카우팅의 그 부분은 댓글을 삭제하는 것이었습니다. 댓글 삭제에 대한 팁도 제가 가장 많이 사용하는 팁 중 하나였습니다.

최근 제거한 주석이 코드 검토에서 다시 나타났습니다.

// filter out contacts that have unsubscribed
$contacts = $unsubscribedFilter->filter($contacts);

// filter out duplicate contacts
$contacts = $duplicateFilter->filter($contacts);

검토자는 내가 코드를 다음과 같이 압축했을 때 "문서를 제거"한 이유를 물었습니다.

$contacts = $unsubscribedFilter->filter($contacts);
$contacts = $duplicateFilter->filter($contacts);

댓글과 문서의 차이점으로 다시 돌아오겠습니다. 지금은 차이점이 있으며 내가 제거한 것은 실제로 주석이었습니다.

먼저, 모든 팀 리더와 엔지니어링 관리자가 외치는 소리에 감사드립니다.

Remove Comments?!!

예, 코드에서 주석을 제거할 것을 제안합니다.

Surely you don't mean removing useful comments?

글쎄, 유용한 의견은 무엇입니까?

댓글과 문서 간의 구분을 백업하고 해결해 보겠습니다. 문서는 형식이 지정된 주석 블록(예: DocBlock, JavaDoc 등)입니다. 댓글은 다른 모든 것입니다.

주석은 무엇을 또는 ​​어떻게가 아니라 왜를 전달해야 합니다. 즉, 코드를 읽어도 전달되지 않는 것이 있으면 주석이 필요할 수 있습니다.

코드 검토로 돌아가서 코드가 전달하지 않은 주석이 전달되지 않았습니다. 할당 및 메서드 이름에서 "중복 연락처 필터링"이라는 것을 유추할 수 있습니다. 따라서 위의 코드 주석은 유용하지 않습니다. 사실, 나는 그것을 읽는 데 시간을 낭비했습니다.

나에게 주석을 제거하는 것은 명확하게 전달되는 코드를 달성하는 것입니다. 가독성을 높이기 위해 코드를 리팩토링할 수도 있습니다. 고려하다:

$contacts->filterUnsubscribed();

댓글은 유용할 뿐만 아니라 오해의 소지가 있습니다. 코드가 변경되어도 진화하지 않은 오래된 댓글을 계속 접하게 됩니다. 최근에 조기에 종료되는 다음 레거시 코드를 수정해야 했습니다.

foreach ($items as $item) {
    if ($item->published) {
        // we've hit the most recent item before this push, so stop looping
        exit;
    }
}

주석에는 루프를 중지하라는 메시지가 표시되지만 코드는 종료됩니다. 나는 무엇을 믿을지 토론하는 데 몇 분을 낭비했습니다. 버그를 감안하여 주석을 따르고 루핑을 중지하도록 코드를 업데이트했습니다. 어쨌든 이 버그는 주석이 없었다면 해결되었을 것입니다. 버그가 있는 코드와 결합하면 득보다 실이 더 많았습니다.

그것이 바로 좋은 일을 하는 것입니다. 당신이 찾은 것보다 더 좋은 것을 남기는 것. 그래서 Boyscouting 이라고 합니다. 삭제할 수 있는 댓글을 발견하면 삭제하세요. 제거할 수 없는 경우 주석을 제거할 수 있도록 코드를 리팩터링할 수 있는지 확인하십시오. 미래의 개발자들은 당신에게 감사할 것입니다. 미래의 개발자가 당신이더라도.

나는 결국 이 전체 게시물을 매우 효과적으로 요약하는 의견에 관한 다음 구절을 발견했습니다.

[comments are] a delicate matter, requiring taste and judgment. I tend to err on the side of eliminating comments, for several reasons. First, if the code is clear, and uses good type names and variable names, it should explain itself. Second, comments aren’t checked by the compiler, so there is no guarantee they’re right, especially after the code is modified. A misleading comment can be very confusion. Third, the issue of typography: comments clutter code.

더 많은 청소 팁을 원하십니까? 진정으로 지속되는 코드를 작성하는 데 도움이 되는 실제 사례가 포함된 "필드 가이드"를 작성하고 있습니다. Sign up 조기 액세스용.