TIL 4장. 주석

TIL (Today I Learned)

2022.02.24 ~ 25

오늘 읽은 범위

4장. 주석

-- 내용을 정리한 글

책에서 기억하고 싶은 내용을 써보세요.

(p. 68 - 69)

• 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 거의 필요하지 않으리라.

• 우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다.

• 때때로 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다.

  그러므로 주석이 필요한 상황에 처하면 곰곰이 생각하기 바란다. 상황을 역전해 코드로 의도를 표현할 방법은 없을까? 코드로 의도를 표현할 때마다 스스로를 칭찬해준다.

• 주석은 오래될수록 코드에서 멀어진다. 이유는 단순하다. 프로그래머들이 주석을 유지하고 보수하기란 현실적으로 불가능하니까.

• 나라면 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다.

• 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.

• 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 우리는 주석을 가능한 줄이도록 꾸준히 노력해야 한다.

• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다. 자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라! (p. 69)

• 어떤 주석은 필요하거나 유익하다. 하지만 명심하기 바란다. 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실을! (p. 70)

• 특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 하니까 마지못해 주석을 단다면 전적으로 시간낭비다. 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다. (p. 76)

• 이해가 안 되어 다른 모듈까지 뒤져야 하는 주석은 독자와 제대로 소통하지 못하는 주석이다. (p. 76)

• 소스 코드 관리 시스템은 누가 언제 무엇을 추가했는지 귀신처럼 기억한다. (p. 86)

오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요

• 내용을 보면서 실제로 과거에 내가 작성했던 (좋지 않은) 주석이 있었다. 최근에는 좋은 이름을 작성하기 위해 노력하며 코드를 짜고 있는데 덕분에 주석이 많은 편은 아니지만 주석을 혹시나 달게 된다면 책에서 나와있는 것처럼 "충분한 시간을 들여 최고의 주석을 달기" 위해 노력해야겠다. 그리고 쓸모없는 주석이 있는지 중간중간 확인하며 불필요한 잡음들을 제거해야겠다는 생각이 들었다.

궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.

--