《읽을 수 있는 코드를 쓰는 예술》 독서노트--주석

주석은 코드에서 매우 중요한 힌트로 다른 사람이나 자신이 이전에 쓴 코드를 읽을 때 종종'미침을 가리키는 역할을 한다.이 독서 노트는 내용을 세 부분으로 나누었다.

Part 1：         
Part 2：        
Part 3：            

Part 1: 주석이 필요하지 않은 경우

코드 자체로 빠르게 추정할 수 있는 사실에 대해 주석을 쓰지 마세요. Q: 왜 주석이 있는 것보다 주석이 없는 것이 더 좋다고 말합니까?A:이 문제는 문장의 오프닝으로 대답할 수 있어요.

주석을 읽는 것은 실제 코드를 읽는 시간을 차지하고, 모든 주석은 화면의 공간을 차지한다.그렇다면, 그것은 가치가 있는 것이 가장 좋다.
다음은'나쁜 맛'이라는 주석을 던져 놓고 느껴보자.

//The class definition for Account
public Account{
  //Construtor
  Account();

  //set the profit member to a new value
  void setProfit(double profit);

  //return the profit from this Account
  double getProfit();
}

이 '고장난 것' 의 주석에서 알 수 있듯이, 이 주석에 첨부된 정보는 아무런 가치가 없고, 게다가 코드의 양도 KPI를 평가하는 데 사용할 수 없기 때문에 이런 주석을 쓰는 것을 절대 금지한다.

나쁜 이름에 주석을 쓰지 말고'가독할 수 있는'코드를 써라. 그러면 상량, 변수, 함수에 좋은 이름을 짓는 것이 첫걸음이다(어떻게 쓰지? 앞으로 보충할 테니 본문은 주석만 토론하자).그러나 좋은 명칭을 생각하기 귀찮아서 해석 작용의 주석을 덧붙여야 하는 경우가 많다.좋은 이름은 좋은 주석이 아니라 좋은 주석이 더 중요하다. 주석은 여러 번만 나타나고 함수나 변수는 여러 번 나타난다.

Part 2: 주석이 필요한 경우

  좋은 주석은'당신의 생각을 기록하라'만 통해 얻을 수 있다. 바로 당신이 코드를 쓸 때의 중요한 생각들이다.코드를 쓰는 측면에서 보면 다음과 같은 몇 가지 상황에 주석이 필요하다.

**'감독 리뷰'가입**

Q:'감독 리뷰'가 뭐야?
'감독 평론'은 바로 영화 제작자가 영화에서 자신의 견해를 제시하고 이야기를 통해 이 영화가 어떻게 제작되었는지 이해하는 데 도움을 주는 것이다.마찬가지로 코드에도 주석을 달아 코드에 대한 가치 있는 견해를 기록해야 한다.
다음은 글의 예를 보여 준다.

//      ，                40%
//         /      

다른 예:

//            。     。 100%     

물론 주석은 왜 코드를 깔끔하게 쓰지 못했는지 설명할 수도 있다. (이것은 코드를 마음대로 쓰도록 격려하는 것이 아니다) 또는 후임자에게 재구성 모자를 쓸 때가 왔다는 것을 일깨워 줄 수도 있다.

//           
//          ‘ResourceNode’       

코드에 하자가 존재하면 코드에 다음과 같은 문제가 존재하면 표에 해당하는 주석을 사용할 수 있다.

표식
보람
TODO
미처 처리하지 못한 일
FIXME
알 수 없는 실행 불가 코드
HACK
한 문제에 대해 어쩔 수 없이 채택해야 하는 비교적 거친 해결 방안
XXX
위험해!여기 중요한 문제가 있어요.
예를 들면 다음과 같습니다.

// TODO        

상수에 주석을 달면 상수를 정의할 때 상수의 배후에는 그것이 무엇인지, 왜 이 값인지에 대한 이야기가 있다.프로그래머로서 이 어떤 값을 선택한 이유는 코드를 읽는 사람들이 모르는 경우가 많기 때문에 독자가 추측할 수 있도록 상량값에 주석을 쓰는 것이 가장 좋다.

NUM_THREADS = 8; //   1   ，   50     

독자의 입장에서 보면 다음과 같은 몇 가지 상황도 주석이 필요하다.

예상했던 질문은 어떤 코드에 대해 다른 사람이 읽을 때'왜 이러는가'라는 의문이 생길 수 있음을 깨달았을 때 이 부분의 코드에 주석을 달아야 한다.

//Force vector to relinquish its merory
vector().swap(data);

가능한 함정을 발표한다. 코드에 의외의 상황이 있을 수 있음을 깨닫게 되면 주석도 첨부해야 한다.

//       0，           
def FixBrokenHtml(html): …

'전역관'주석은 팀에 새로운 구성원이 가입할 때'전역관'을 갖춘 주석은 곧 원래의 코드를 읽을 수 있게 할 것이다.하나의 예를 제시한다:

//             ，                 
//                

'총결성'주석'총결성'주석과'전역관'주석은 약간 비슷하지만 이것은 종종 하나의 유형이나 함수 내부로 여러 함수나 프로그램 문장을 총결산한다.하나의 예를 제시한다:

//       
private String classname="com.mysql.jdbc.Driver";
private String dbConntctedURL = "*******";
private String user = "root";
private String password = "*******";

Part 3: 간단명료한 주석 ###

'작가의 심리적 정체'극복 Q:'작가의 심리적 정체'는 무엇입니까?A:쉽게 말하면 프로그래머가'게을러'라고 쓴'게을러'예요.작가의 심리적 정체를 극복하려면 유일한 방법은 쓰는 것이다.처음에는 마음속의 생각을 먼저 쓴 다음에 점차적으로 추출하고 개선할 수 있다.여러 번 순환한 후에 너는 손에 쥐는 대로 잡는 경지에 이르렀다.다음은 책에서 구체적인 조작의 몇 가지 요점을 언급한 것이다.

코드의 의도 성명

메모를 간결하게 유지

정보량이 많은 단어를 채택

윤색이 거친 문장

불명확한 대명사 사용을 피하는 예:

//Insert the data into the cache, but check if it's too big fist

'it'가 가리키는 것은 도대체 데이터입니까, 아니면 캐치입니까?밑에 거로 바꾸면 훨씬 이해가 돼요.

//Insert the data into the cache, but check if the data too big fist

함수를 정확하게 설명하는 행위는 함수를 썼다고 가정하고 파일의 줄 수를 통계한다:

//Return the number of lines in this file.
int CountLines(String filename);

위의 주석은 정확하지 않다. 왜냐하면 잘못된 뜻이 존재하거나 몇 가지 특별한 상황이 있기 때문이다.

""(빈 파일)--0 또는 1행?

"hello"--0 또는 1행?

"hello"- 1 또는 2줄?

"hello world"--1 또는 2행?

  하지만 당신이 쓴 주석이 이렇다면:

//Count how many newline bytes('
') are in the file
int CountLines(String filename);

입력/출력 예로 특별한 상황을 설명하고 주석에 대해 간혹 정성스럽게 고른 입력/출력 예가 천만 마디보다 더 효과적일 때가 있다.

//Remove the suffix/prefix of 'chars' from the input 'src'
String Strip(String src, String chars)();

위의 주석을 보았는데 문제가 생겼다.chars는 전체적으로 제거할 하위 문자열입니까, 아니면 무질서한 알파벳입니까?src 엔딩에 chars가 여러 개 있으면 어떨까요?분명히 정성들여 고른 예는 질문에 완벽하게 대답할 수 있다.

//…
//Example：Strip("ab", "a") returns "/a/"
String Strip(String src, String chars)();