최고의 댓글은 우리가 쓰지 않는 댓글입니다.

"좋은 댓글"에 대한 여러 기사를 읽었고written some "좋은 댓글"에 대한 기사read technical books를 읽었으며 모든 항목에 주석을 달아야 하는 JavaScript 프로젝트(jsdoc)에서 작업합니다. 나는 그 문제에 대해 생각을 바꿨다.

⚠️ 기술 및 비즈니스에 대한 내 블로그 게시물on my personal blog을 더 읽어보세요! ⚠️

자체 문서화 코드

내 경험과 독서를 통해 배운 내용은 이 게시물의 제목으로 요약할 수 있습니다.

The best comments are the ones we don't write.

주석을 작성해야 할 필요성을 느끼는 경우는 일반적으로 코드가 명확하고 깨끗하지 않기 때문입니다.

이것을 비교하십시오 :

function main() {
  let imageName = 'test.png'

  // Get the extension off the image filename  
  let pieces = imageName.split('.')
  let extension = pieces.pop()
}

댓글 자체가 나쁜건 아닙니다. 개발자는 나중에 코드를 더 잘 이해하기 위해 필요할 수 있다고 판단할 수 있습니다. 그는 댓글을 달았습니다. 좋습니다.

그러나 그것은 일종의 변명처럼 보입니다. "내 코드는 추악하고/복잡하지만 그렇게 나쁘지는 않습니다. 주석으로 설명하겠습니다."

function main() {
  let imageName = 'test.png'
  let extension = getFileExtension(imageName)
}

함수의 이름은 이미 코드 부분이 무엇을 하는지에 대한 질문에 대답해야 합니다. 이 가능성을 사용하지 않는 이유는 무엇입니까?

너무 많은 주석은 코드를 질식시킨다

위에 표시된 대로 현재 프로젝트에서 모든 것을 문서화해야 합니다. 모든 것은 jsdoc로 주석 처리되어야 합니다.

그것에 대해 나쁜 것은 없습니다. 그러나 결국 대부분의 서면 주석은 테스트를 통과하기 위한 목적으로만 사용되는 주석입니다. 중복되고 쓸모가 없습니다.

/**
 * Get the extension of the file
 * 
 * @param {string} filename - The filename
 * @return {string} the extension of the file  
 */
function getFileExtension(filename) {
  let pieces = imageName.split('.')
  return pieces.pop()
}

코드를 읽는 동안 얻지 못한 댓글에 정보가 있다고 말해주세요?아무것도 없습니다.

반대로 함수가 파일의 확장자를 반환한다는 사실은 함수 이름에 한 번, 함수 설명에 한 번, @return 태그에 한 번 총 세 번 반복됩니다.

이 댓글의 부가 가치는 무엇입니까? 없습니다.

쓸데없는 댓글을 계속 보게 되면 뇌는 무시하는 법을 배웁니다. 당신은 아마도 이전에 이것을 경험했을 것입니다. 우리가 위에서 본 것과 같이 많은 댓글과 대부분의 댓글이 있는 프로젝트에서 더 이상 댓글을 보거나 읽지 않게 됩니다.

불행히도 몇 가지 흥미로운 댓글은 쓸모없는 댓글의 바다에서 길을 잃고 있어야 할 만큼 유용하지 않습니다.

문서에 의한 코드 커버리지

단위 테스트에 관해서는 문서에 의한 주석의 코드 커버리지를 측정하기 위해 현재 존재하는 많은 도구가 있습니다.

그리고 단위 테스트의 경우 100% 커버리지에 빠르게 도달하고 싶은 유혹을 느낍니다.

그리고 단위 테스트에 관해서는 이것이 가치 있는 일인지 확신할 수 없습니다. 단위 테스트의 경우 높은 적용 범위는 신뢰할 수 없으며 품질 증명이 아닙니다. 문서의 경우 높은 비율의 적용 범위는 비생산적이지 않으며 코드를 질식시킵니다.

개발자가 모든 곳에서 문서를 작성하도록 강요함으로써 우리는 그들이 불완전한 문서를 작성하도록 강요합니다.

코드가 깨끗한 곳에서는 주석이 쓸모가 없으며 두뇌는 곧 무시할 것입니다. 코드가 지저분한 경우 개발자는 주석을 코드를 업그레이드하지 않는 핑계로 사용합니다.

나는 댓글을 적게 쓴다.

… 그리고 그것은 나쁜 것이 아닙니다. 코드를 읽기가 더 쉽습니다. 내 코드를 가능한 한 자명하게 만들도록 강요합니다. 따라서 코드가 더 깨끗해집니다. 독자들은 내가 쓰는 몇 가지 댓글에 더 많은 관심을 기울일 것입니다.

오늘 내가 직면하고 있는 유일한 문제는 자동 생성된 공개 문서가 있는 프로젝트의 맥락에 있습니다. 내 의견에서 생성된 문서가 완전한지 확인하면서 중복을 피하는 방법.


더 깊이 파고들기 위해 여기에 제시된 개념/아이디어를 더 자세히 설명하는 최신 게시물이 있습니다. 독자의 피드백과 질문을 따릅니다.

La documentation sera toujours utile