TIL (Today I Learned)

2022.02.24

오늘 읽은 범위

4장. 주석

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

• 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.[68]

• 주석은 '순수하게 선하지' 못하다. 사실상 주석은 기껏해야 필요악이다.[68]

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

• 주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.[68]

• 진실은 한 곳에만 존재한다. 바로 코드다. 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다.[69]

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

• 이해가 안 되어 다른 모듈까지 뒤져야 하는 주석은 독자와 제대로 소통하지 못하는 주석이다. 그런 주석은 바이트만 낭비할 뿐이다.

• 소스 코드 관리 시스템이 우리를 대신해 코드를 기억해준다. 이제는 주석으로 처리할 필요가 없다. 그냥 코드를 삭제하라. 잃어버릴 염려는 없다. 약속한다.

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

• 회사에 입사하고 처음으로 배정받은 프로젝트는 전임자는 이미 퇴사하고 3년 정도 중단되어 있던 프로젝트였다. 처음 프로젝트 파일을 열었을 때, 모듈화는 물론이고 아무런 계획없이 코드가 main 파일에 모두 담겨있었다. 그 중 가장 힘들었던 것은 바로 주석이였다. 코드의 길이는 1000줄을 가뿐히 뛰어 넘었는데 그 원인은 주석이였다. 언제 코드를 추가했는지 무엇을 삭제했는지 수정한 사람의 이니셜을 사용해서 주석으로 모두 남겨두었으며(git과 svn을 사용하는 회사라는 점에서 이해가 안된다.) 100줄에 가까운 함수를 통째로 주석처리한 코드도 있었다. 주석을 제거하다 보니 삭제를 해야하는지 아니면 그냥 두어야 하는지 코드를 이해하기 위해 보낸 시간이 너무나 길었고 결과적으로 주석만 모두 삭제하고 나니 전체 길이는 700줄 정도로 줄어들었다.

• 주석으로 이렇게 바이트 낭비를 하고 있었다니...그저 놀라울 뿐이였고 소스코드를 받은 순간부터 기존 코드의 이해를 위해서 주석을 사용했을 뿐 이니셜로 기록하는 짓은 하지 않았다.(생각해보면 리팩토링을 제대로 할 수 있는 좋은 기회였지만 신입으로서 도전하기에는 어려움이 있었다.)

• 나는 주석을 잘 사용하는 편이라 생각했지만 돌이켜 보면 무의미하거나 주석만 남겨놓고 코드를 삭제하거나 이동시켜 나에게 혼란을 주는 주석들을 많이 만들고 있었다. 표현력이 부족하다는 말이 실감이 되었다. 프로그래머로써 코드로 나의 의도를 표현할 수 있는 능력을 키워야겠다.

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