[클린코드] 2022-02-25 TIL

TIL (Today I Learned)

2022.02.25

 

오늘 읽은 범위

4장. 주석

 

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

• 나쁜 코드에 주석을 달지 마라. 새로 짜라. (p.68)
• 저작권 정보와 소유권 정보와 같은 법적인 이유로 회사가 정립한 표준에 맞춰서 주석을 작성하는 것은 타당하다. (p.70)
• 경우에 다라 해당 방식으로 구현하게 된 의도를 주석으로 작성해주면 코드에 대한 이해도를 향상시킬 수 있다. (p.71)
• 인수나 반환값이 표준 라이브러리나 변경 불가능한 코드에 속하는데 그 의미가 한 눈에 드러나지 않는다면 주석을 사용하는 것도 좋다. ex) JAVA - a.compareTo(b) == 0 // a == b (p.72)
• 주석을 프로그램의 결과에 대한 경고로 활용할 수도 있다. 그를 통해 다른 프로그래머의 시간을 절약시키고 실수로 면하게 할 수 있다. (p.73)
• Todo 주석은 프로그래머가 활용하기 좋은 주석이다. Todo 주석을 활용하는 예시로는 구현할 부분, 문제 해결 요청, 코드 변경이 필요한 부분 표시 등이 있으며 작업이 처리될 때마다 해당 주석을 제거하는 것이 중요하다. (p.75)
• 주석을 통해 코드에서 중요한 부분을 강조할 수 있다. (p.75)
• 코드의 내용을 그대로 주석이 이야기해서는 안 된다. 주석은 코드가 표현하지 못하는 내용만을 담고 있어야 한다. (p.77)
• 의무적으로 주석을 달지는 말자. 어차피 달아봤자 보기에 복잡해지기만 하고 잘못된 정보를 제공할 수도 있다. (p.80)
• 소스코드 이력을 주석으로 남길 필요는 없다. 우리에게는 버전 관리 시스템이 존재한다. (p.81)
• 안 쓰는 코드는 주석으로 남기는 것이 아니라 꼭 지우자. (p.86)
• 읽는 사람이 몰라도 되는 정보는 굳이 적지 않는다. (p.89)

 

 

 

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

• 주석과 관련된 내용들은 워낙 유명하기도 하고 쉽게 요약될 수 있어서 별로 어렵다고 느낀 챕터는 아니었다. 결국 주석은 최대한 사용하지 말고 '코드를 잘 짜라'는 내용이다 요약한다면. 결국 프로그래머가 주석을 얼마나 제대로 활용할 수 있는지는 함수를 얼마나 잘 만들 수 있는지, 변수를 얼마나 직관적으로 만들어줬는지 등에 따라 달린 것 같다. 물론 주석을 활용해야 하는 경우도 존재한다. 여태까지 내 경험을 기준으로 주석이 필요했던 순간들의 대표적인 예시는 '알고리즘 혹은 공식을 활용할 때 그에 대한 언급', 'Todo 내용 기록', 'string format 표현' (예를 들어서 javascript의 Date 객체를 가지고 YYYY-MM-DD 형식으로 바꿔주는 getYYYYMMDDStrFromDate 함수를 만들었을 때 연도, 월, 날짜가 들어간다는 내용 말고 구체적인 형식을 표현하기 위해 나는 주석을 활용했다. "'YYYY-MM-DD' 형식의 문자열 반환"과 같이 말이다. 내가 생각하기에 이 부분은 필요해서 주석을 적어두는데 다른 사람들의 관점은 어떨지 모르겠다.), '기획의 관점에서 프로그램 로직의 이유 설명' (예를 들어서 이전 회사에서 모바일 어플리케이션을 만들 때 일부 특수한 이벤트 핸들링에 대해서 '고객이 ~한 행동을 할 경우에 대한 처리'와 같은 코드를 삽입했다. 나는 예외적 경우라고 생각해서 명시하는 것이 좋다고 생각했는데 이것이 틀릴 수도 있을 것 같다.) 등이 있다. 그 중 일부는 주석이 실제로는 필요하지 않았을 것도 존재할 것이고 또 한편으로는 내가 미처 주석을 적지 않았으나 주석을 달았다면 훨씬 더 좋은 코드가 완성되었을 경우도 있었을 수 있다. 결국 주석을 필요할 때만 뽑아 쓰는 능력은 다른 사람들과 일을 많이 해보면서 차근차근 쌓아갈 문제라고 생각된다. 우선적으로는, 주석을 뭘 쓰지보다 단순하게 '주석은 진짜 쓰지말자!'라는 마인드로 코드 자체를 다듬어가는 과정이 중요한 것 같다.

 

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

• Javadocs : JDK와 함께 패키지로 제공되는 특수 도구로 HTML 형식으로 Java 소스 코드의 문서를 작성하는 데 사용된다. '문서 주석'이라는 것을 활용하여 자바의 모든 클래스를 문서화 해주며 소스코드 문서 외에도 Java 어플리케이션 구조 분석에 활용되는 'doclet' 혹은 'taglet'을 생성하게 해준다. 컴파일 과정에서 모든 주석은 삭제되기 때문에 Javadoc을 위한 주석이 프로그램의 동작에 영향을 끼치는 경우는 존재하지 않는다.