Community

개발자 99% 커뮤니티에서 수다 떨어요!

← Go back
TIL: 4. Comments
#clean_code
2년 전
386

TIL (Today I Learned)

2022.02.25

오늘 읽은 범위

  1. 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.