Skip to content

Conversation

@rlawlstjd0077
Copy link

@rlawlstjd0077 rlawlstjd0077 commented Mar 16, 2021

해야 할 일

배포 준비

  • Javadoc 작성하기
  • API 문서 만들기
  • Docker image 만들기

트레이너님 안녕하세요 :) 이번 한주도 잘 부탁드립니다. 🙏😁

상품 관련 클래스에 설명을 추가하였습니다.
유저 관련 클래스에 설명을 추가하였습니다.
인증 관련 클래스에 설명을 추가하였습니다.
Javadoc 주석이 누락된 클래스에 설명을 추가하였습니다.
@rlawlstjd0077
Copy link
Author

2021-03-16

진행내역

  • 클래스 일괄 Javadoc 주석 작성

Copy link
Collaborator

@johngrib johngrib left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

오래간만입니다. 주석을 아주 깔끔하게 잘 작성해주셔서 읽기 좋았습니다.

User save(User user);

/**
* 전달받은 email과 일치하는 유저의 존재 여부를 반환합니다.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

여부라는 단어는 컨텍스트에 따라 의미가 모호할 수 있습니다.

Suggested change
* 전달받은 email과 일치하는 유저의 존재 여부를 반환합니다.
* 전달받은 email과 일치하는 유저가 존재한다면 true를, 그렇지 않다면 false를 리턴합니다.

Copy link
Author

@rlawlstjd0077 rlawlstjd0077 Mar 17, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

그렇군요 .. 다만 궁금해지는 것이 말씀해주신 여부의 의미가 모호해 지는 경우가 어떤 경우가 있을까요 ?

그리고 궁금해서 String 클래스의 javadoc을 보니 아래와 같이 반환타입이 boolean 메소드들의 표현이 조금씩 다른 것을 볼 수 있었는데요
표현이 다른 이유는 스타일 차이라고 보면 될까요 ?

Screen Shot 2021-03-17 at 6 03 20 PM

  • (만약 이렇다면 .. ) true를 반환한다.

Screen Shot 2021-03-17 at 6 02 31 PM

  • (만약 이렇다면 .. ) true를 하고 그렇지 않다면 false를 반환한다.

Screen Shot 2021-03-17 at 6 01 55 PM

  • Test 라는 표현은 신선했습니다..

Copy link
Collaborator

@johngrib johngrib Mar 17, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

표현이 다른 이유는 작성자들이 다르기도 하고(모두 사람입니다 :-) ), 미묘한 차이가 있기 때문이기도 합니다. 여부를 제가 좋지 않다고 생각하는 이유는 여부가 boolean을 의미하는 두 값을 한꺼번에 표현하기 때문이에요.

다음과 같은 코드가 가장 심각한 경우입니다.

/* 인증 기간이 지나지 않았는지 여부. */

괜찮은 습관을 갖춘 프로그래머라면 이렇게 작성하지 않겠지만, 오랜 세월을 거친 방대한 코드를 유지보수하다보면 숱하게 만납니다. 이런 주석을 보면 주석만으로 판단을 할 수가 없죠. 몇 줄 아래로 내려가서 구현체를 봐야 합니다.

하지만 다음과 같이 작성하면 주석만 보고도 1초 안에 상황 파악이 끝납니다.

/* 인증 기간이 지났다면 true, 지나지 않았다면 false를 리턴합니다. */

여부는 별 문제 없어 보인다는 점에서, 아주 가끔씩 치명적인 주석을 작성할 위험이 있는 단어입니다.
그래서 저는 이 단어를 쓰는 것이 나쁜 습관이라 생각해요.

Copy link
Contributor

@MagicalLas MagicalLas Mar 17, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

개인적으로는 여부보다는 ~면 true, 아니면 false가 더 명확하게 이해되는 것 같아요. 저에게 여부와 비슷한 단어로는 확인이나 검증(validate)이 있어요.

if(check_request(request)){
    do_something();
} else{
    do_something();
}

위에 코드가 있고 check_request함수의 주석에 "request가 올바른지 확인합니다"만 주석에 있다면 저는 true를 반환하면 문제가 없다는걸까? false를 반환하면 문제가 없다는걸까?라는 생각이 들 것 같아요.

가끔 저게 제가 생각한것과 반대라서 실수했던 적이 있어서요ㅠㅠ

Copy link
Author

@rlawlstjd0077 rlawlstjd0077 Mar 18, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

피드백 감사합니다 :):)
생각해보면 /* 인증 기간이 지나지 않았는지 여부. */ 라는 주석은 고개를 조금만 돌려도 어렵지 않게 볼 수 있는 것 같습니다.
(물론 그 중에는 제가 작성했던 주석도 있다는 게 함정이지만 😂)
별 문제 없어 보인다는 점 이라는 말이 정말 무섭게 다가오는 군요.

라스님의 설명 해주신 예제는 더 현실적이어서 이해하는데 많은 도움이 되었습니다.
여기까지 와서 피드백 해주시다니 정말 감사해요 🙏🙂

이전의 모호한 표현의 Javadoc 주석을 보다 나은 표현의 주석으로 교졍하였습니다.
Spring REST Doc 관련 필요 의존성들을 추가하였습니다.
이전의 모호한 표현의 Javadoc 주석을 보다 나은 표현의 주석으로 교졍하였습니다.
asciidoc을 이용하여 기본적인 형태의 Spring REST Doc 을  작성하였습니다.
앞으로는 무긍무진한 리팩토링 모험을 하게 될 예정입니다.
이전에는 Request/Response 예시만 있어서 불친절 했다.
Request/Response Field 를 명시 해주어 표현력을 높이고자 하였다.
이전에는 Request/Response 예시만 있어서 불친절 했다.
Request/Response Field 를 명시 해주어 표현력을 높이고자 하였다.
@rlawlstjd0077
Copy link
Author

rlawlstjd0077 commented Mar 18, 2021

2021-03-18

진행내역

  • API 문서 작성 (V0.0.1)
    • Request/Response 예시 표현
  • API 문서 작성 (V0.0.2)
    • Request/Response 필드 설명 추가

API 문서를 점진적으로 발전 시켜 나가는 식으로 작업을 진행하고 있는데 생각보다 즐겁네요 :)
(아마 내일까지는 계속 발전시켜나가지 않을까 싶습니다 .. )
감사합니다. 🙏

);
}

public static ResponseFieldsSnippet getProductDataResponseFieldsSnippet() {
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ProductControllerTest 에서 반복적으로 쓰이는 Snippet 들을 별로 분리한 Fixture 클래스를 선언해보았습니다.
다만 메서드 이름이 직관적이지 못한 것 같아 맘에 들지 않네요.
수정이 필요해 보입니다.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

이름이 엄청 길긴 하네요. 접근제한은 public으로 하지 마시고 private으로 하는 것이 좋겠습니다.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

package-private 을 말씀 하시는 걸까요 ???

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

public이 아니면 아무거나 상관없을 것 같아요.

이전에는 Request/Response 예시만 있어서 불친절 했다.
Request/Response Field 를 명시 해주어 표현력을 높이고자 하였다.
Copy link
Collaborator

@johngrib johngrib left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

커밋 메시지 본문이 재미있습니다.
c496a8c
image

}

sourceCompatibility = '1.8'
sourceCompatibility = '15'
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

와 15!

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

와 ! 말도 없이 몰래 바꿔 버렸군요 ,, ㅎㅎㅎ

브라우저에서 REST Doc을 볼 수 있도록 jar 패키징 시에 REST Doc을 static resource로 포함하도록 gradle, web config 설정을 추가하였습니다.
이전 구현에서는 REST DOC 설정을 위한 옵션들을 모든 클래스들에 정의를 해줘야 했습니다.
그래서 옵션들을 정의한 상위 클래스를 선언하고 이를 확장하도록 리팩토링 하였습니다.
[카카오 REST API 문서](https://developers.kakao.com/docs/latest/ko/kakaologin/rest-api) 를 참고하여 API Request, Response 표현 포맷을 보기 좋게 변경하였다.
@rlawlstjd0077
Copy link
Author

Custom한 필드를 추가 하려고 Snippet을 커스마이징 하는 방법에 대해서 알아보게 되었는데 그 과정에서 공부한 내용들을 공유합니다 🙂

Snippet Customize 해보기

  • 일부 스니펫의 필드를 수정하거나 추가하고 싶다면 REST Doc 기본 템플릿을 커스마이징할 수 있습니다.
  • 기본적으로 스니펫은 mustache 문법을 사용합니다.
  • 커스마이징할 스니펫의 기본 템플릿은 여기에서 확인할 수 있습니다.

request-field 스니펫을 수정해보자

  • 간단하게 default-request-fields.snippet 을 커스터마이징 해보겠습니다
    • request-field 중 필수 값 여부를 나타내는 필수값 필드를 추가해보았습니다.
    • mustache 문법 중 {{^param}}{{/param}} 은 param이 비어 있거나 false 일 때 작동한다고 합니다.

request-field.snippet

===== Request Fields
|===
|필드명|타입|필수값|설명

{{#fields}}
|{{#tableCellContent}}`+{{path}}+`{{/tableCellContent}}
|{{#tableCellContent}}`+{{type}}+`{{/tableCellContent}}
|{{#tableCellContent}}{{^optional}}true{{/optional}}{{/tableCellContent}}     //필수값 필드를 추가함
|{{#tableCellContent}}{{description}}{{/tableCellContent}}

{{/fields}}

|===
  • 이후에 작성된 request-field.snippet 파일을 src/test/resources/org/springframework/restdocs/templates 경로에 넣어주면
  • 이렇게 변경된 것을 볼 수 있습니다 !

Screen Shot 2021-03-19 at 4 10 34 PM

참고: https://woowabros.github.io/experience/2018/12/28/spring-rest-docs.html

@rlawlstjd0077
Copy link
Author

2021-03-19

진행 내역

  • API 문서 작성 (V0.0.3)
    • Kakao REST API 문서 참고 하여 API 문서 포맷 변경
  • REST Doc JAR 패키징 시에 static resource 에 포함되도록 적용

오늘은 뭔가 굉장히 열심히 작업을 했다고 생각이 들었는데 막상 돌아보면 별로 한게 없는 것 같은 느낌이 듭니다 😂

Copy link
Collaborator

@johngrib johngrib left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

846f5d4 좋은 커밋 메시지지만 조금 더 짧게 써도 좋았을 거에요. 리팩토링: REST API 테스트 설정을 상위 클래스로 분리하라 였다면 어땠을까요?
image

Copy link
Collaborator

@johngrib johngrib left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

917c892 커밋 메시지와 작업 내용이 다릅니다. 실수로 만든 커밋이라면 git rebase -i를 통해 drop 할 수 있어요.
image

Copy link
Collaborator

@johngrib johngrib left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

eb2833a
리팩토링: User, Product 테스트에 사용되는 Fixture 클래스의 메소드 이름의 표현력을 개선하라

이걸 이렇게 작성했다면 어땠을까요?
팩토링: User, Product 테스트 Fixture의 이름을 더 쉽게 고쳐라

@rlawlstjd0077
Copy link
Author

rlawlstjd0077 commented Mar 20, 2021

2021-03-20

진행내역

질문

  • 종립 트레이너님은 커밋은 주로 터미널로 하신 다고 이야기 하신 것을 보았는데 변경사항을 체크하고 staging 을 하실 때에는 어떤 커맨드를 사용하시나요?

@rlawlstjd0077
Copy link
Author

eb2833a
리팩토링: User, Product 테스트에 사용되는 Fixture 클래스의 메소드 이름의 표현력을 개선하라

이걸 이렇게 작성했다면 어땠을까요?
팩토링: User, Product 테스트 Fixture의 이름을 더 쉽게 고쳐라

개인적으로는 좋은 것 같습니다.
커밋 메시지 역시 가능하다면 최대한 간결한게 더 좋은 것 같네요 !

jre 이미지를 기반으로 어플리케이션을 패키징하여 실행하는 도커 이미지를 추가하였습니다.
jre 이미지를 쓴 이유는 도커 이미지의 경량화를 위함이며 해당사항은 [병호님 PR](https://github.com/CodeSoom/spring-week8-assignment-1/pull/3#discussion_r595165959)을 참고하였습니다.
배포 환경에서는 기본으로 h2 memory db를 사용하도록 설정하였습니다.
maria db를 사용하는 설정은 profile로 추가하였습니다.
@rlawlstjd0077
Copy link
Author

846f5d4 좋은 커밋 메시지지만 조금 더 짧게 써도 좋았을 거에요. 리팩토링: REST API 테스트 설정을 상위 클래스로 분리하라 였다면 어땠을까요?
image

이 피드백 역시도 동의합니다 :)
돌아보니 조금더 갈결하게 수정할 수 있는 개선의 여지가 있다고 느껴지는 커밋 메시지인 것 같습니다.

[카카오 REST API 문서](https://developers.kakao.com/docs/latest/ko/kakaologin/rest-api) 를 참고하여 API Request, Response 표현 포맷을 보기 좋게 변경하였다.
jre 이미지를 기반으로 어플리케이션을 패키징하여 실행하는 도커 이미지를 추가하였습니다.
jre 이미지를 쓴 이유는 도커 이미지의 경량화를 위함이며 해당사항은 [병호님 PR](https://github.com/CodeSoom/spring-week8-assignment-1/pull/3#discussion_r595165959)을 참고하였습니다.
배포 환경에서는 기본으로 h2 memory db를 사용하도록 설정하였습니다.
maria db를 사용하는 설정은 profile로 추가하였습니다.
@rlawlstjd0077
Copy link
Author

rlawlstjd0077 commented Mar 20, 2021

트레이너님 안녕하세요 !
피드백 주신 것을 보고 rebase drop을 시도해보았는데 그 과정에서 제가 엄청난 짓(?)을 저지른 것 같아 도움을 조금 요청 하고 싶습니다 😂

작업의 타임라인은 이러했습니다..

  1. git rebase -i 를 통해서 drop 하고자 하는 커밋을 선택

Screen Shot 2021-03-20 at 10 10 59 PM

  1. source tree에서 변경 사항을 보고 pull 을 해버림 ..
  • 이때 drop된 사항을 반영하기 위해서 git push --force 를 했어야 했을까요 ?

Screen Shot 2021-03-20 at 10 12 17 PM

  1. 원격 저장소의 이력이 반영됨

Screen Shot 2021-03-20 at 10 18 17 PM

  1. 이후에 git rebase -i 를 다시 시도해 보면 The previous cherry-pick is now empty, possibly due to conflict resolution. 라는 메시지가 전시됨 ..

Screen Shot 2021-03-20 at 10 31 09 PM

git에 대한 이해도가 부족해서 이후에 어떻게 접근을 해야 될 지 모르겠어서 멘붕이 왔습니다 .. ㅎㅎ
어떤 방식으로 접근을 하면 좋을까요? 만약 개념이 필요하다면 어떤 개념의 학습이 필요할까요 ?

@johngrib
Copy link
Collaborator

johngrib commented Mar 20, 2021

  • 이때 drop된 사항을 반영하기 위해서 git push --force 를 했어야 했을까요 ?

네. 그렇게 했어야 합니다.

  1. 이후에 git rebase -i 를 다시 시도해 보면 The previous cherry-pick is now empty, possibly due to conflict resolution. 라는 메시지가 전시됨 ..

git rebase --abort로 리베이스를 취소하고 git reset --hard f5d1로 처음으로 되돌렸다면 좋았겠군요.

git에 대한 이해도가 부족해서 이후에 어떻게 접근을 해야 될 지 모르겠어서 멘붕이 왔습니다 .. ㅎㅎ
어떤 방식으로 접근을 하면 좋을까요? 만약 개념이 필요하다면 어떤 개념의 학습이 필요할까요 ?

git을 여기에서 언급하는 건 꽤나 방대한 일이 될 수 있어서 아쉽군요.
제가 추천하는 방법은 딱 두 가지입니다.

  1. Pro Git 책을 읽는다. 한국어 버전도 무료로 공개되어 있습니다.
  2. 자신의 블로그나 개인 프로젝트를 git을 사용해 매일 관리한다.

하지만 가장 좋은 것은 git을 잘 쓰는 사람과 같이 일을 하는 것인데요... 음. 좋은 방법이 없을지 생각을 좀 해봐야겠네요.

@rlawlstjd0077
Copy link
Author

git을 여기에서 언급하는 건 꽤나 방대한 일이 될 수 있어서 아쉽군요.
제가 추천하는 방법은 딱 두 가지입니다.

  1. Pro Git 책을 읽는다. 한국어 버전도 무료로 공개되어 있습니다.
  2. 자신의 블로그나 개인 프로젝트를 git을 사용해 매일 관리한다.

하지만 가장 좋은 것은 git을 잘 쓰는 사람과 같이 일을 하는 것인데요... 음. 좋은 방법이 없을지 생각을 좀 해봐야겠네요.

추천 감사합니다 :)
프로젝트 과제를 진행할 때 책을 읽어보면서 많은 시도를 해봐야 될 것 같습니다 !

@johngrib
Copy link
Collaborator

Pro Git은 꼭 읽어보세요. 공식 홈페이지에서 추천하고 있는 유일한 책입니다. 다른 책은 읽지 않아도 되고, 이거 한 권만 읽어도 충분합니다.

Copy link
Collaborator

@johngrib johngrib left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

한 주간 고생 많으셨습니다.

@johngrib johngrib merged commit 48fe8e7 into CodeSoom:rlawlstjd0077 Mar 21, 2021
@rlawlstjd0077
Copy link
Author

rlawlstjd0077 commented Mar 21, 2021

한 주간 너무 감사했습니다 !!

hannut91 pushed a commit that referenced this pull request Dec 27, 2022
* chore: RestDocs 문서 관련 gradle 설정

* feat: RestDocs 문서 생성을 위한 provider, util 생성

* docs: Product API asciidoc 스니펫 생성 작업

* docs: Product API 문서화
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants