개발자 99% 커뮤니티에서 수다 떨어요!
TIL (Today I Learned)
2022.02.25
오늘 읽은 범위
4장. 주석
책에서 기억하고 싶은 내용을 써보세요.
좋은 주석
정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석(p.70)
법적인 주석
회사가 정립한 구현 표준에 맞춰 법적인 이류로 특정 주석을 넣으라고 명시한다.(p.70)
정보를 제공하는 주석
때로는 기본적인 정보를 주석으로 제공하면 편리하다. 주석이 유용하다 할지라도, 가능하다면, 함수 이론에 정보를 담는 편이 더 좋다.(p.71)
결과를 경고하는 주석
테스트 케이스를 꺼야하는 이유를 설명하는 주석(p.73)
요즘에는 @Ignore 속성을 이용해 테스트 케이스를 꺼버린다. 하지만 JUnit4가 나오기 전에는 메서드 이름 앞에 _기호를 붙이는 방법이 일반적인 관례였다.(p.74)
TODO 주석
TODO 주석은 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술한다. 더 이상 필요 없는 기능을 삭제하라는 알림, 누군가에게 문제를 봐달라는 요청, 더 좋은 이름을 떠올려달라는 부탁, 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의 등에 유용하다.(p.74)
나쁜주석
주절거리는 주석
특별한 이유없이 의무감으로 혹은 프로세스에서 하라고 하니까 마지못해 주석을 단다면 전적으로 시간낭비다. 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다. (p.76)
같은 이야기를 중복하는 주석
자칫하면 코드보다 주석을 읽는 시간이 더 오래 걸린다. (p.77)
의무적으로 다는 주석
코드를 복잡하게 만들며, 거직말을 퍼뜨리고, 혼동과 무질서를 초래한다.(p.80)
이력을 기록하는 주석
이제는 혼란만 가중 할 뿐이다. 완전히 제거하는 편이 좋다.(p.81)
위치를 표시하는 주석
배너 아래 특정 기능을 모아놓으면 유용한 경우도 있긴 있다. 하지만 일반적으로 주석은 가독성만 낮추므로 제거해야 마땅하다.(p.85)
공로를 돌리거나 저자를 표시하는 주석
이런 주석은 그냥 오랫동안 코드에 방치되어 점차 부정확하고 쓸모없는 정보로 변하기 쉽다.(p.86)
주석으로 처리한 코드
주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다. 그래서 쓸모 없는 코드가 점차 쌓여간다. (p.86)
소스코드 관리 시스템이 우리를 대신해 코드를 기억해준다. 그냥 코드를 삭제하라. 잃어버릴 염려는 없다. (p.87)
전역정보
주석을 달아야 한다면 근처에 잇는 코드만 기술하라. 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라.(p.88)
함수 헤더
짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.(p.89)
비공개 코드에서 Javadocs
공개하지 않을 코드라면 Javadocs는 쓸모가 없다. 시스템 내부에 속한 클래스와 함수에 Javadocs를 생성할 필요는 없다. (p.90)
오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요
주석은 도움이 되라고 다는 것일텐데 주석이 있다는 것 자체가 작성된 코드로 그걸 보는 프로그래머에게 내용을 충분히 설명을 못했다는 증거라는 말에 반성을 하게 된다. 그리고 형상관리 툴이 있는데 코드를 지우지 않고 주석으로 처리했던 기억이 난다. 일을 하면서 작성되어있는 코드들을 보며 잘못된 방법들을 배우고 있었던 것 같아서 아쉽기도하고 책을 읽으면서 그동안 봤던 것들을 경험으로 나은 방법을 배우는 것 같아서 좋기도하고 그렇다. 책으로도 예제와 시범을 보여주긴 하지만 나쁜코드와 주석 예제를 가지고 리팩터링하는 시범을 보여줬다는 강의 굉장히 재밌었을거 같다.
긴 함수명이 한눈에 들어오지 않기도 하고 함수명 짓는 것도 어려운데 영어공부를 열심히 해야할 것 같다는 생각이든다....
궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.
javadoc : JDK와 함께 패키지로 제공되는 특수 도구입니다. Java 소스 코드에서 HTML 형식의 API 문서를 생성하기 위해 Sun Microsystems에서 작성한 문서 생성기입니다.