jaehyun: CleanCode Chapter 4~8

CleanCode/jaehyun/CleanCode_Chapter_04.md

@@ -0,0 +1,129 @@
+4장 주석
+=============
+"나쁜 코드에 주석을 달지 마라. 새로 짜라."
+주석은 필요악이다. 주석은 코드의 변화에 맞춰 유지보수되기 어렵고 결국 시간이 갈수록 코드와 거리가 멀어지고 
+잘못된 정보를 준다. 잘못된 주석은 없는 것보다 훨씬 더 나쁘다. 우리는 가능한 주석없이 코드로 의도를 표현해야한다.
+코드만이 정확한 정보를 제공하는 유일한 출처다. 
+
+* 주석은 나쁜코드를 보완하지 못한다.
+일반적으로 나쁜코드(알아먹기 어려운)를 보완하기 위해 주석으로 부연설명을 하려고 하지만 그 시간에 
+코드를 정리하는게 낫다.
+
+* 코드로 의도를 표현하라!
+많은 경우 주석으로 달려는 설명을 함수 이름으로 만들어 표현해도 충분하다.
+
+* 좋은 주석. 
+물론 주석이 필요한 아래 같은 경우들이 있다. 그래도 주석은 없는게 좋다.
+
+  - 법적인 주석.
+  소스 파일 첫머리에 들어가는 저작권 정보와 소유권 정보 주석
+
+  - 정보를 제공하는 주석.
+  함수 입출력 형식이나 정보를 알려주는 경우, 하지만 구체적인 이름과 구조를 수정해서 주석을 줄 일 수 있다.
+
+  - 의도를 설명하는 주석.
+  구현 설명을 넘어 결정에 깔린 의도를 설명 하는 경우.
+
+  - 의미를 명료하게 밝히는 주석.
+  인수나 반환 값이 표준 라이브러리나 변경하지 못하는 코드에 속할 때, 의미를 명료하게 밝히는 주석.
+  하지만 주석이 올바른지 검증하기 어려움으로  더 나은 방법이 없는지 고민하고 정확히 달도록 주의.
+
+  - 결과를 경고하는 주석.
+  다른 프로그래머의 실수를 방지하거나 결과를 경고 하는 목적의 주석.
+
+  - TODO 주석.
+  다음 함수를 구현하지 않은 이유와 미래 모습을 TODO 주석으로 설명. 필요하지만 당장 구현하기 어려운 업무를 기술. 
+  문제를 봐달라는 요청, 더 좋은 이름을 떠올려 달라는 부탁, 앞으로 발생할 이벤트에 맞춰 고드를 고치라는 주의 등.
+  하지만 나쁜 코드를 남겨 놓는 핑계로 사용해서는 안된다. 주기적으로 TODO주석을 점검해 필요없을 경우 없애는게 좋다.
+
+  - 중요성을 강조하는 주석.
+  자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위한 주석.
+
+  -  공개 API에서 Javadocs.
+  공개용 API의 도움말. 물론 다른 주석처럼 잘못된 정보를 전달할 가능성이 존재하니 주의. 
+
+* 나쁜 주석.
+대부분의 주석은 이 범주에 속한다. 허술한 코드를 변명하는 프로그래머의 독백...
+
+  - 주절거리는 주석.
+  특별한 이유없이 의무감 혹은 프로세스에서 정해서 별 생각 없이 다는 주석. 
+  주석을 달기로 결정했으면 충분한 시간을 들여 최고의 주석을 달기 위해 노력해야 한다. 
+  다른 사람이 주석을 통해 정보를 얻을 수 없거나 이해를 못하면 그냥 혼자 주절거린 주석이다.
+
+  - 같은 이야기를 중복하는 주석.
+  코드 내용을 그대로 설명 하는 주석. 추가적인 정보를 주는 것도 아니고 주석을 읽은 사람이 코드를 부정확하게 이해하고
+  대충 넘기게 만들 수 있다.
+
+  - 오해할 여지가 있는 주석.
+  엄밀하게 주석을 달지 못하면 살짝 잘못된 정보나 생략된 내용의 주석을 보고 코드를 잘못 사용 할 수 있다.
+
+  - 의무적으로 다는 주석.
+  의도가 있어서 가 아니라 정해진 규칙 때문에 무조건 작성한 주석.
+
+  - 이력을 기록하는 주석.
+  첫머리에 모듈에 가한 변경을 모두 기록하는 주석, 버전 관리 시스템이 없던 시절 관습으로 이제는 없는 게 좋다.
+
+  - 있으나 마나 한 주석.
+  당연하게 알 수 있을 정보를 쓸데없이 주석으로 달면 독자가 주석을 무시하게 되고, 
+  정작 중요한 정보를 제공하는 주석도 무시할 수 있다.
+
+  - 무서운 잡음.
+  때로는 Javadocs도 잡음이다. 목적없고 형식적인 주석은 생각없이 쓰게 되고 더 실수하기 쉽게 된다.
+
+  - 함수나 변수로 표현할 수 있다면 주석을 달지 마라.
+  주석이 필요하지 않도록 코드를 개선하는 편이 더 좋다.
+
+  - 위치를 표시하는 주석.
+  ////// Something ///// 등으로 코드에서 위치를 표시하기 위한 배너로 주석을 사용하는 경우. 자주 사용하지 않으면 
+  확실하게 주의를 끌 수 있지만 자주 사용되면 독자가 흔한 잡음으로 여겨 무시하게 되고 가독성만 떨어뜨린다. 
+  그러므로 반드시 필요할 때만, 아주 드물게 사용하는 편이 좋다.
+
+  - 닫는 괄호에 다는 주석.
+  복잡한 중첩문에서 닫는 괄호에 주석을 달아 범위를 표시하기 위한 주석. 주석 대신 함수를 줄이려 시도하자.
+  작고 캡슐화된 함수라면 필요 없을 것이다.
+
+  - 공로를 돌리거나 저자를 표시하는 주석.
+  소스 코드 관리 시스템을 이용하자.
+
+  - 주석으로 처리한 코드.
+  주석 처리된 코드는 다름 사람들이 지우기 주저한다. 결국 방치되고 점점 쌓여간다. 
+  소스 코드 관리 시스템이 코드를 우리 대신 기억해 준다. 주석 치지 말고 지우자.
+
+  - HTML 주석.
+  소스 코드에서 HTML 주석은 혐오 그 자체다.
+
+  - 전역 정보.
+  주석을 달아야 한다면 근처에 있는 코드만 기술하라. 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라.
+  코드와 주석이 붙어있지 않으면 주석의 최신화를 유지하기 더 어렵다.
+
+  - 너무 많은 정보.
+  주석에 흥미로운 역사나 관련 없는 정보를 늘어놓지 마라. TMI 금지.
+
+  - 모호한 관계.
+  주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다. 주석이 다시 설명을 요구하면 안된다.
+
+  - 함수 헤더.
+  짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.
+
+  - 비공개 코드에서 Javadocs.
+  공개용이 아니면 불필요하다.
+
+
+ 느낀점
+=============
+1장에서 저자는 '코드는 요구사항은 정밀하게 표현하는 언어' 라고 말했다. 이 말과 일맥상통하는 내용 인듯하다.
+주석으로 코드를 자세하게 설명하려는 시도 자체가 모순적이라고 말한다는 느낌을 받았다.
+코드는 좋은 이름과 구조, 추상화를 통해 스스로 설명이 되어야 하고 주석은 그 외 필요한 정보를 제공할때만
+써야 한다고 말하는 듯 하다.
+
+또 주석의 등장 빈도에 대해서도 여러 번 경고를 하는데, 주석이 정말 중요할 때 한번씩 등장해야 사람들이 주의를
+기울여서 살펴보지 시도 때도 없이 등장해서는 무시될 수 밖에 없다는 점도 반복적으로 강조했다.
+
+어째든 주석을 사용하지 않으려면 좋은 코드를 만들어야 한다는 생각을 다시 한번 하게 된다는게 중요한 것 같다.
+
+
+논의 사항
+=============
+
+저는 다른 사람이 가져다 써야 하는 기능을 만들 때 뭐라도 주석으로 설명하고 싶은 마음이 자주 들었습니다..
+주석을 특별히 자주 사용하게 되는 경우가 있으신지 궁금합니다.

CleanCode/jaehyun/CleanCode_Chapter_05.md

@@ -0,0 +1,106 @@
+5장 형식 맞추기
+=============
+프로그래머라면 형식을 깔끔하게 맞춰 코드를 짜야 한다. 코드 형식을 맞추기 위한 간단한 규칙을 정하고 
+그 규칙을 착실하게 따라야 한다. 필요하다면 규칙을 자동으로 적용하는 도구를 활용한다.
+
+* 형식을 맞추는 목적.
+코드 형식은 중요하다! 너무 중요해서 융통성 없이 맹목적으로 따르면 안 된다. 코드 형식은 의사소통의 일환이다.
+맨 처음 잡아놓은 구현 스타일과 가독성 수준은 유지보수 용이성과 확장성에 계속 영향을 미친다.
+원래 코드는 사라질지라도 개발자의 스타일과 규율은 사라지지 않는다.
+
+* 적절한 행 길이를 유지하라.
+자바 기준 500줄에서 200줄 정도인 파일들로 커다란 시스템을 구축할 수 있다. 반드시 지켜야할 규칙은 아니지만
+일반적으로 큰 파일보다 작은 파일이 이해하기 쉽다.
+
+* 신문 기사처럼 작성하라.
+소스 파일 첫 부분은 고차원 개념과 알고리즘을 설명한다. 아래로 내려갈수록 의도를 세세하게 묘사한다.
+마지막에는 가장 저차원 함수와 세부 내역이 나온다.
+
+* 개념은 빈 행으로 분리하라.
+각 행은 수식이나 절을 나타내고, 일련의 행 묶음은 완결된 생각 하나를 표현한다. 
+생각 사이는 빈 행을 넣어 분리해야 마땅하다. 빈 행은 새로운 개념을 시작한다는 시각적 단서다.
+
+* 세로 밀집도.
+줄바꿈이 개념을 분리한다면 세로 밀집도는 연관성을 의미한다. 즉, 서로 밀접한 코드 행은 세로로 가까이 놓여야 한다. 
+연관된 내용이 '한 눈'에 들어 오면 읽기 쉽다.
+
+* 수직 거리.
+서로 밀접한 개념은 세로로 가까이 둬야 한다. 두 개념이 서로 다른 파일에 속한다면 규칙이 통하지 않지만, 타당한
+근거가 없다면 서로 밀접한 개념은 한 파일에 속해야 마땅하다. protected 변수를 피해야 하는 이유 중 하나다.
+같은 파일에 속할 정도로 밀접한 두 개념은 세로 거리로 연관성을 표현한다. 연관성이란 한 개념을 이해하는 데
+다른 개념이 중요한 정도다. 연관성 깊은 두 개념이 멀리 떨어져 있으면 코드를 읽는 사람이 소스 파일과 클래스를
+여기저기 뒤지며 위아래로 뺑뺑이 돌게 만든다.
+
+  - 변수 선언.
+  변수는 사용하는 위치에 최대한 가까이 선언한다. 우리가 만든 함수는 매우 짧으므로 지역 변수는 각 함수 맨 처음에
+  선언한다. 루프를 제어하는 변수는 흔히 루프 문 내부에 선언한다. 아주 드물게 다소 긴 함수에서 블록 상단이나 루프
+  직전에 변수를 선언하는 사례도 있다.
+
+  - 인스턴스 변수.
+  인스턴스 변수는 클래스의 맨 처음에 선언한다. 변수 간에 세로로 거리를 두지 않는다. 선언 위치에 대해서는 논쟁이
+  분분 하지만 잘 알려진 위치에 인스턴스 변수를 모은다는 사실이 중요하다. 변수 선언을 어디서 찾을 지 모두가
+  알고 있어야 한다.
+
+  - 종속 함수.
+  한 함수가 다른 함수를 호출한다면 두 함수는 세로로 가까이 배치한다. 또한 가능하다면 호출하는 함수를 호출되는
+  함수보다 먼저 배치한다. 그러면 프로그램이 자연스럽게 읽힌다.
+
+  - 개념적 유사성.
+  개념적인 친화도가 높을수록 가까이 배치한다. 친화도는 높은 예시는 앞선 경우처럼 한 함수에서 다른 함수를 
+  호출하는 경우, 변수와 그 변수를 사용하는 함수 등 직접적인 종속성이 있는 경우가 한 예다. 그 외 에도 친화도를 
+  높이는 요인으로 비슷한 동작을 수행하는 일군의 함수가 좋은 예다. 이런 경우 종속적인 관계가 없더라도 가까이
+  배치할 함수들 이다.
+
+  - 세로 순서
+  일반적으로 함수 호출 종속성은 아래 방향으로 유지한다. 호출되는 함수를 호출하는 함수보다 나중에 배치한다.
+  그러면 소스 코드를 모듈이 고차원에서 저차원으로 자연스럽게 내려간다.
+  신문 기사와 마찬가지로 가장 중요한 개념을 가장 먼저 표현한다. 이때 세세한 사항을 최대한 배제한다.
+  세세한 사항은 가장 마지막에 표현한다. 그러면 독자가 소스 파일에서 첫 함수 몇 개만 읽어도 개념을 
+  파악하기 쉬워진다.
+
+* 가로 형식 맞추기.
+일반적으로 한 행수는 20에서 60행 정도를 보인다. 프로그래머는 명백하게 짧은 행을 선호한다. 짧은 행이 바람직하다.
+행수를 지나치게 제한할 필요는 없지만 100에서 120자 이상이라면 주의 부족이다.
+
+* 가로 공백과 밀집도.
+가로로는 공백을 사용해 밀접한 개념과 느슨한 개념을 표현한다.
+할당 연산자를 사용할때 좌우에 공백을 줘서 두 요소가 확실히 나뉜다는 사실이 명확해 진다.
+반면, 함수 이름과 이어지는 괄호 사이에는 공백을 넣지 않는다. 함수와 인수는 서로 밀접하기 때문이다.
+공백을 넣으면 한 개념이 아니라 별개로 보인다. 괄호 안 인수는 공백으로 분리해 쉼표를 강조해서 인수가 별개
+임을 보여준다. 연산자 우선순위를 강조하기 위해서도 공백을 사용한다. 이때, 코드 형식을 자동으로 맞춰주는
+도구는 대다수가 연산자 우선순위를 고려하지 못해서 수식에 같은 간격을 적용한다.
+
+* 가로 정렬.
+정렬이 필요할 정도로 목록이 길다면 문제는 목록 길이지 정렬 부족이 아니다.
+또한, 정렬을 통해 코드를 읽을 때 불필요한 부분이 강조될 수 있다.
+
+* 들여쓰기.
+들여쓰기는 범위로 이뤄진 계층을 표현한다. 들여쓰기가 없으면 인간이 코드를 읽기란 거의 불가능하리라.
+때로는 간단한 if 문, 짧은 while 문, 짧은 함수에서 들여쓰기를 무시하고 싶은 유혹이 생긴다.
+하지만, 책의 저자는 한 행에 범위를 뭉뚱그린 코드보다 들여쓰기로 범위를 제대로 표현한 코드를 선호한다.
+
+* 가짜 범위.
+빈 while문 이나 for문은 좋지 않다. 하지만 쓴다면 세미콜론을 새 행에 제대로 들여써서 제대로 표시한다.
+
+* 팀 규칙.
+프로그래머라면 각자 선호하는 규칙이 있다. 하지만 팀에 속한다면 팀 규칙을 따라야 한다. 그래야 일관적인
+스타일을 보인다. 좋은 소프트웨어 시스템은 읽기 쉬운 문서로 이뤄진다는 사실을 기억해야한다.
+
+
+ 느낀점
+=============
+그냥 보기 좋아서, 다들 그렇게 하고 자동으로 그렇게 되니까 익숙해진 부분까지 자세한 이유를 분석하고
+코드의 평균적인 길이 등 신선한 내용이 있었다.
+> 할당 연산자를 사용할 때 좌우에 공백을 줘서 두 요소가 확실히 나뉜다는 사실이 명확해 진다.
+
+이런 식으로 까지 생각해 본적은 없었는데 신선했다...
+
+
+
+논의 사항
+=============
+``` return b*b - 4*a*c ```
+수식을 작성할 때 책처럼 가로 공백을 신경쓰시는지 궁금합니다. 
+
+``` return (b * b) - (4 * a * c) ```
+저는 보통 위 같이 그냥 다 공백을 주고 괄호로 묶어 버리는데 갑자기 궁금하네요..