TIL (Today I Learned)

2022.02.25

오늘 읽은 범위

4. Comments (pp.53-74)

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

• Comments are not "pure good." Indeed, comments are, at best, a necessary evil.

• The proper use of comments is to compensate for our failure to express ourself in code.

• Code changes and evolves. Unfortunately the comments don't always follow them - can't always follow them.

• Inaccurate comments are far worse than no comments at all.

• Truth can only be found in one place: the code. Only the code can truly tell you what it does.

• Therefore, though comments are sometimes necessary, we will expend significant energy to minimize them.

Comments Do Not Make Up for Bad Code (p.55)

• Clear and expressive code with few comments is far superior to cluttered and complex code with lots of comments.

• Rather than spend your time writing the comments that explain the mess you've made, spend it cleaning that mess.

Explain Yourself in Code (p.55)

• It's simply a matter of creating a function that says the same thing as the comment you want to write.

Good Comments (p.55)

• Keep in mind, however, that the only truly good comment is the comment you found a way not to write.

Legal Comments (p.55)

• For example, copyright and authorship statements are necessary and reasonable things to put into a comment at the start of each source file.

Informative Comments (p.56)

• It is sometimes useful to provide basic information with a comment.

• It is better to use the name of the function to convey the information where possible.

Explanation of Intent (p.56)

• Sometimes a comment goes beyond just useful information about the implementation and provides the intent behind a decision.

Clarification (p.57)

• Sometimes it is just helpful to translate the meaning of some obscure argument or return value into something that's reasonable.

• In general, it is better to find a way to make that argument or return value clear in its own right; but when its part of the standard library, or in code that you cannot alter, then a helpful clarifying comment can be useful.

• A clarifying comment is incorrect.

Warning of Consequences (p.58)

• Sometimes it is useful to warn other programmers about certain consequences.

TODO Comments (p.58)

• "To do" notes in the form of //TODO comments.

• TODOs are jobs that the programmer thinks should be done, but for some reason can't do at the moment.

• Whatever else a TODO might be, it is not an excuse to leave bad code in the system.

Bad Comments (p.59)

• Most comments fall into this category.

• Usually they are crutches or excuses for poor code or justifications for insufficient decisions, amounting to little more than programmer talking to himself.

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

• It seems like the author is really reluctant to use comments in general. I agree that code itself should be self-explanatory, but I still think comments are still useful. In my case, I usually start with code part first when I read other code pieces and I move onto comment part if I cannot smoothly understand the code.

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

• For lots of examples in this chapter, it is hard for me to understand.