search

AI-Research-Center-Homepage / frontend

AI-Research-Center-Homepage Front
3 stars 0 forks source link

주석 convention #22

Closed baaaam771 closed 2 years ago

baaaam771 commented 2 years ago

코드 사이에 들어가는 여러줄 주석과 상세한 설명이 필요한가 이부분은 다같이 고민해보고 따로 규칙을 정하면 좋을거 같습니다!

Originally posted by @suinj8 in https://github.com/AI-Homepage-Practice-Frontend/AI-Homepage/pull/13#pullrequestreview-963468047

baaaam771 commented 2 years ago

📒 이슈 내용

comment convention

📑 상세 내용

  1. 코드에 여러줄 상세 설명 주석 필요한가
  2. 함수, 클래스 설명을 위한 주석 스타일 규칙

✔️ 체크리스트

baaaam771 commented 2 years ago

기존 방식

image
baaaam771 commented 2 years ago
image

저는 일전에 이와 같은 방식을 사용했는데요

코드에 상세한 주석 설명을 추가할 때 함수, 클래스 주석 설명과 뚜렷한 구분이 필요해보여서 경계선을 길게 설정해뒀습니다 경계선 부분에 관련해 이야기를 나눠보고 함수, 클래스 주석 설명에 해당 함수의 이름을 적어 놓는 칸도 추가적으로 필요해보입니다 이부분도 이야기 나눠보기를 원합니다

LimEunSang commented 2 years ago

추가적으로 주석 Convention

/* @author LimEunSang, dmstkd2905@naver.com @date 2022-05-07 @description name, content, image 등이 포함된 게시글 컴포넌트 */

  1. 이 부분 date를 최초 작성 날짜로 하는 게 맞을까요, 마지막 수정 날짜로 하는 게 맞을까요?
suinj8 commented 2 years ago

함수나 클래스 설명하는 주석방식은 스타일에 관련된 부분이라 무엇을 선택하던 크게 상관은 없어 보입니다.

개인적인 생각입니다만 중간중간 상세하게 여러줄로 설명하는 주석은 필요 없다고 생각합니다. 중간에 설명하는 주석이 많이 달려있으면 코드가 전체적으로 길어지고 그만큼 지저분해 보일것 같아요. 다른 많은 페이지를 가봐도 여러줄의 상세한 주석이 달려있는건 볼 수 없구요.

아마 코드의 동작 방식이나 props같은 부분은 서로 다 이해한다는 가정하게 작업을 하니까 그런것이 아닐까 생각합니다. 코드에 관한 상세적인 부분이나 모르는 부분은 서로 댓글로 물어보고 이해하는것이 좋지 않을까 생각합니다.

LimEunSang commented 2 years ago

코드 중간중간 사용하는 설명 주석은 애매하긴하네요. 쉬운 내용은 설명이 필요없고 복잡한 로직에 대해선 주석 설명이 있으면 확실히 좋을거같은데 쉽고 복잡한건 사람 수준별로 상대적일거라서. 그래서 저는 코드작성자가 주석설명이 필요하다 싶으면 작성하는 것이 좋다고 생각합니다.

euny0ung commented 2 years ago

저도 날짜를 마지막 수정일로 하는건지 최초 작성일로 하는건지 궁금합니다. 저는 마지막 수정일로 했는데 다른 분들은 어떻게 하셨나요??

그리고 중간에 넣는 주석은 안넣어도 될것 같습니다. 제 주관적인 생각이지만, mui를 기반으로 코드를 작성하고 있기 때문에 엄청 어렵다고 느껴지는건 없는것 같습니다. 만약 모르는 부분이 있다면 직접 물어보는게 낫다고 생각해요! 처음보는건 스스로 검색하고 공부하는게 도움이 많이 되기도 하고요. 그런데 만약 복잡한 css를 사용하게 되면 그 부분은 자세히 주석을 쓰는게 나을것 같아요. 본인이 css 기능을 다 외우고 있는게 아닌 이상... 저번 스터디에서 느꼈습니다ㅎㅎ

suinj8 commented 2 years ago

추가적으로 주석 Convention

/* @author LimEunSang, dmstkd2905@naver.com @Date 2022-05-07 @description name, content, image 등이 포함된 게시글 컴포넌트 */

  1. 이 부분 date를 최초 작성 날짜로 하는 게 맞을까요, 마지막 수정 날짜로 하는 게 맞을까요?

저는 방안이 몇가지가 생각나긴 하는데

  1. 그냥 date에 마지막 수정일로 한다
  2. description 가장 끝에 마지막 수정일을 적는다 
    /**
*https://github.com/author LimEunSang, [dmstkd2905@naver.com](mailto:dmstkd2905@naver.com)
*@Date 2022-05-07
*@description name, content, image 등이 포함된 게시글 컴포넌트
*                      설명설명설명설명설명설명설명설명설명설명설명
*                      설명설명설명설명설명설명설명설명설명설명설명
*                      Update 2022-05-08
*/
  3. update 부분을 새로 만든다(Update에는 가장 최근 변경일) 
    /**
*https://github.com/author LimEunSang, [dmstkd2905@naver.com](mailto:dmstkd2905@naver.com)
*@Date 2022-05-07
*@Update 2022-05-08
*@description name, content, image 등이 포함된 게시글 컴포넌트
*                      설명설명설명설명설명설명설명설명설명설명설명
*                      설명설명설명설명설명설명설명설명설명설명설명
*/

저는 3번이 깔끔해보입니다. 다른 의견 있으실까요?

euny0ung commented 2 years ago

저도 3번이 제일 좋은것 같습니다.

baaaam771 commented 2 years ago

date를 표기하는 가장 근본적인 이유는 패키지 같은 것들이 버전 업그레이드가 되었을 때 사용 방식이 변하게 되는데 이 때 업데이트를 빠르게 적용시켜주기 위해서 입니다. 그러니 마지막 수정날짜를 표기해주셔야 해당 method를 업데이트 해줄지 말지 빠르게 판단이 가능해집니다 그래서 제가 처음에 카톡으로 보내준 주석 양식에는 data 대신 version이라고 표기해뒀습니다 결론적으로 날짜 표기 빠른 업데이트가 목적입니다. 그래서 어짜피 수정시 날짜를 변경해줘야하고 최초 생성 날짜는 큰 의미가 없는것 같아서 1번이 좋은 것 같습니다

baaaam771 commented 2 years ago

/**

LimEunSang commented 2 years ago

date를 표기하는 가장 근본적인 이유는 패키지 같은 것들이 버전 업그레이드가 되었을 때 사용 방식이 변하게 되는데 이 때 업데이트를 빠르게 적용시켜주기 위해서 입니다. 그러니 마지막 수정날짜를 표기해주셔야 해당 method를 업데이트 해줄지 말지 빠르게 판단이 가능해집니다 그래서 제가 처음에 카톡으로 보내준 주석 양식에는 data 대신 version이라고 표기해뒀습니다 결론적으로 날짜 표기 빠른 업데이트가 목적입니다. 그래서 어짜피 수정시 날짜를 변경해줘야하고 최초 생성 날짜는 큰 의미가 없는것 같아서 1번이 좋은 것 같습니다

그런 의도였는지 처음 알았네요. 기존의 방식을 사용하되 마지막 수정 날짜를 적어주는 것이 정답인거같아요.

LimEunSang commented 2 years ago

코드 중간 여러 줄 설명 주석에 관한 제 생각입니다. 만약 코드를 엄청 어렵게 힘들게 구현했는데 7일 뒤에 보면 까먹을 거 같거나 남이 이해하기 힘들 거 같으면 전체 코드 라인수가 길어지고 지저분해 보일지라도 써야하는게 맞다고 봅니다. 또 본인 코드만 본인이 수정한다는 보장도 없기 때문에 미래에 유지보수할 나 또는 다른 사람을 위해서라도 ""필요한 경우에 한에"" 개발에서 주석은 필수라고 생각합니다~

코드 리뷰를 진행할 때 저도 상대방이 작성한 코드를 이해하기 위해 mui docs를 참고하면서 비교하고 이해하면서 공부하고 있습니다만, 현재 주는 공부가 아니라 개발이기 때문에 ""필요한 코드에 한에"" 친절한 주석이 있으면 그만큼 코드 리뷰 하는 시간도 짧아지고 개발 시간을 단축시키는 좋은 효과가 있다고 봅니다.

결론 : 무조건 여러 줄 주석을 작성하지 말자는 의견에는 반대. ""본인이 판단해서 필요하면"" 여러 줄 주석 작성할 수 있도록 하자.

suinj8 commented 2 years ago

<긴 주석: 필요하면 다는걸로 결론> <date: 가장 최신 날짜 기준으로 작성>