Ch.11 Design it Twice
It’s unlikely that your first thoughts about how to structure a module or system will produce the best design. You’ll end up with a much better result if you consider multiple options for each major esign decision: Design it twice
Even if you are certain that there is only one reasonable approach, consider a second esign anyway, no matter how bad you think it will be.
Make a list of the procs and cons of each one.
-
Does one alternative have a simpler interface than another?
-
Is one interface more general-purpose than another?
-
Does one interface enable a more efficient implmentation than another?
Or you may discover that you cna combine features of multiple alternatives into a new design that is better than any of the original choices.
Designing it twice does not need to take a lot of extra time. You may not need more than an hour or two to consider alternatives. This is a small amount of time compared to the days or weeks you will spend implmeneting the class.
No-one is good enough to get it right with their first try.
The design-it-twice approach not only improves your designs, but it also improves your design skills. The process of devising and comparing multiple approaches will teach you about the factors that make designs better or worse.
Ch.12 Why Write Comments? The Four Execuses
Documentation also plays an important role in abstraction; without comments, you can’t hide complexity. Finally, the process of writing comments, if done correctly, will actually improve a system’s design. -> comments can hide complexity
- Good comments can make a big difference in the overall quality of software
- It isn’t hard to write good comments
- Writing comments can actually be fun
12.1 Good code is self-documenting
There is still a significant amount of design information that cna’t be represented in code.
Reading code is time-consuming and painful. If the method does anything nontrivial, you wil break it up into several smaller methods. This will result in a large number of shallow methods.
To understand the behavior of top-level method, readers will probably need to understand the behaviors of the nested methods.
- If users must read the code of a method in order to use it, then there is no abstraction; *
12.2 I don’t have time to write comments
…
Ch.13 Comment Should Describe Things that Aren’t Obvious from the Code
… comments record this information so that developers who come along later can easily understand and modify the code. Comments should describe things that aren’t obvious from the code.
One of the most important reasons for comments is abstraction. (복잡하고 읽기어려운 코드보다 한줄의 코멘트)
Developers should be able to understand the abstraction provided by a module without reading any code other than its externally visible declarations.
13.1 Pick conventions
If you are programming in an environment where there are no existing conventions to follow, try to adopt the conventions from some other language or project that is similar.
Conventions serve two purposes. First, they ensure consistency, which makes comments easier to read and understand. Second, they help to ensure that you actually write comments. (코멘트가 있어야할곳에 코맨트가 있어야한다.)
- Interface
A common block that immediately precedes the declaration of a module such as a class, data structure, function, or method. The comment describes the module’s interface.
- Data structure member
A comment next to the declaration of a field in a data structure, such as an instance variable or static variable for a class.
- Implementation comment
A comment inside the code of a method ooor function, which describes how to code works internally.
- Cross-module comment
A comment describing dependencies that cross module boundaries.
Every class should have an interface comment, every class variable should have a comment, and every method should have an interface comment.
13.2 Don’t repeat the code
Many comments are not particularly helpful. The most common reason is that the comments repeat the code.
A first step towards writing good comments is to user different words in the comment from those in the name of the entity being described. Pick words for the comment that provide additional information about the meaning of the entity, rather than just repeating its name.
13.3 Low-level comments add precision
Comments augment the coode by providing information at a different level of detail. 코드와 같은 레벨이라면 코멘트의 의미가 없다.
Precision is most useful when commenting variable declarations such as class instance variable, method arguments, and return value. 보통 변수명은 짧기때문에 자세히 코멘트를 달아주면 좋다.
if a null value is permitted, what does it imply?
if a variable refers to a resource that must eventually be freed or closed, who is responsible for freeing or closing it?
The most common problem with comments for variable is that the comments are too vague. -> 그래서 자세히 써주는 코멘트가 필요하다.
명사를 기준으로 코멘트를 달아라 Ture 는 ~~ false는 ~
13.4 Higher-level comments enhance intuition
Ch 18. Code should be obvious
