PHP 코드 주석 작은 세부 사항

코드 자체보다 코드 주석이 더 중요하다고 할 수 있습니다. 저는 신입사원들에게 댓글을 쓰는 습관을 길러야 한다고 경고하고 싶습니다. 그렇지 않으면 다른 사람에게 해를 끼칠 뿐 자신에게 이익이 되지 않을 것입니다. 코드에 작성한 주석이 친근하게 작성되도록 하는 몇 가지 방법은 다음과 같습니다. 요약하자면 "해야 할 일 5가지와 하지 말아야 할 것 3가지"
1. 독자가 이미 알고 있는 내용을 반복하지 마세요(×)
메서드명과 코드만 봐도 함수가 보이면 코멘트를 작성할 필요가 없습니다.

// If the color is red, turn it green
if (color.is_red()) {
  color.turn_green();
}

2. 추론 및 이력을 주석으로 처리합니다. (√)
코드의 비즈니스 로직을 향후 업데이트하거나 변경해야 할 경우 댓글을 남겨야 합니다. :

으으3. 한 줄에 너무 긴 댓글은 쓰지 마세요(×)
가로 스크롤 막대를 드래그하는 것과 같은 것은 없습니다. 댓글을 읽은 개발자는 더욱 분노했습니다. 실제로 대부분의 개발자는 이러한 주석이 읽기 불편하기 때문에 무시하기로 결정합니다.

/* The API currently returns an array of items
even though that will change in an upcoming ticket.
Therefore, be sure to change the loop style here so that
we properly iterate over an object */
var api_result = {items: ["one", "two"]},
    items = api_result.items,
    num_items = items.length;
for(var x = 0; x < num_items; x++) {
  ...
}

넷째, 논리보다 긴 댓글을 올리고 뒤에 짧은 댓글을 배치하세요 (√)
댓글은 120자를 초과하지 않는 경우 코드 옆에 배치할 수 있습니다. 그렇지 않은 경우 주석은 명령문 바로 위에 배치되어야 합니다.

rree5. 댓글을 위해 불필요한 댓글을 달지 마세요. (×)
불필요한 설명은 혼란을 야기할 수 있습니다. 어쩌면 학교에서 개발자가 더 잘 이해하는 데 도움이 될 모든 문장을 주석 처리하도록 배웠을 수도 있습니다. 그러나 이것은 잘못된 것입니다. 누구든지 그런 말을 하면 당장 뺨을 때려주세요. 코드가 깨끗하고 간결하게 유지되어야 한다는 것은 말할 필요도 없습니다. 코드에 한 줄씩 설명이 필요한 경우 가장 중요한 일은 리팩터링입니다.

function Person(name) {
  this.name = name;
  this.first_name = name.split(" ")[0]; // This is just a shot in the dark here. If we can extract the first name, let's do it
}

6. 댓글의 철자는 정확해야 합니다 (√)
코드를 철자하지 마세요. 댓글 실수에 대해 변명하기. IDE에서 맞춤법을 검사할 수 있습니다. 이 기능이 없다면 플러그인을 다운로드하여 직접 사용해 보세요!

7. 연습을 더 많이 하세요 (√) 연습이 완벽을 만듭니다. 유용한 댓글을 작성해 보고 다른 개발자에게 귀하의 댓글이 유용한지 물어보세요. 시간이 지나면 무엇이 친절한 댓글인지 알게 될 것입니다.

8. 다른 사람의 댓글 검토 (√) 코드 검토 중에는 Note 확인을 무시하는 경향이 있습니다. 더 많은 의견을 묻는 것을 두려워하지 말고 질문을 해야 합니다. 모두가 좋은 메모를 쓰는 좋은 습관을 들이면 세상은 더 나은 곳이 될 것입니다.

9. 댓글에 대해 꼭 알아야 할 필수 요약 댓글은 개발 과정에서 매우 중요한 부분이지만, 댓글을 위해 댓글을 달아서는 안 됩니다. 주석은 유용하고 간결해야 하며 코드를 보완해야 합니다. 주석은 코드를 한 줄씩 설명하는 데 사용되어서는 안 되며, 대신 비즈니스 논리, 추론 및 향후 영향을 설명하는 데 사용해야 합니다.