From e3b5920cfee74ceccaa620e8ac0bbf4a981ec838 Mon Sep 17 00:00:00 2001 From: chamny20 Date: Mon, 28 Nov 2022 14:49:04 +0900 Subject: [PATCH 1/2] chaemin: about remark --- remark.txt | 194 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 remark.txt diff --git a/remark.txt b/remark.txt new file mode 100644 index 0000000..4e702bb --- /dev/null +++ b/remark.txt @@ -0,0 +1,194 @@ +우리가 주석을 쓰는 이유는? + +=> 유용한 정보를 제공해주기 위함 or 알아보기 쉽게 하기 위함 + +좋은 주석, 나쁜 주석 설명에 앞서... + +"나쁜 코드에 주석을 달지 마라. 새로 짜라." + +=> 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 애초에 주석이 필요없는 방향으로 에너지를 쏟는 게 좋다. +=> 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다! + + + +[좋은 주석] + +0. 코드로 의도를 표현해라! + +- 주석으로 의도를 표현한 코드 +//직원에게 복지 혜택을 받을 자격이 있는지 검사 +if((employee.flags & HOURY_FLAG) && (Employee.age>65)) + +- 만약 코드로 의도를 표현한다면? +if(employee.isEligibleForFullBenefits()) + +=> 한눈에 파악 가능 + +1. 정보를 제공하는 주석 + +// 테스트 중인 Responder 인스턴스를 반환한다. +protected abstract Responder responderInstance(); + +2. 의도를 설명하는 주석 + +3. 의미를 명료하게 밝히는 주석 + +assertTrue(a.compareTo(a) == 0 ) // a == a +assertTrue(a.compareTo(b) != 0 // a != b +assertTrue(a.compareTo(c) == -1) // a < c + +4. 결과를 경고하는 주석 + +@Ignore("여유 시간이 충분하지 않다면 실행하지 마세요."); +public void testCode() { + ... +} + +=> @Ignore 어노테이션을 통해 테스트 케이스를 off시킬 수 있다. + +5. TODO 주석 +앞으로 할 일을 //TODO로 남겨두면 편하다. + +//TODO-function 현재 필요하지 않다. +//체크아웃 모델을 도입하면 함수가 필요없다. +function makeVersion(): VersionInfo | null { + return null; +} + + + +[나쁜 주석] +보통 특별한 이유 없이 의무감으로 주석을 다는 경우에 나쁜 주석을 쓸 가능성이 잦다. + +1. 같은 이야기를 반복하는 주석 + +// this.closed가 true일 때 반환되는 유틸리티 메소드다. +// 타임아웃에 도달하면 예외를 던진다. +public synchronized void waitForClose(final long timeoutMillis){ + if(!closed){ + throw new Exception(""); + } +} + +=> 여기에 있는 주석은 코드에 있는 내용을 그대로 가져왔기 때문에 그닥 도움이 되지 않는 주석이다. + +2. 의무적으로 다는 주석 + +/** +* +* @param title CD 제목 +* @param author CD 저자 +* @param tracks CD 트랙 숫자 +* @param durationInMinutes CD 길이(단위: 분) +*/ +public void addCD(String title, String author, int tracks, int durationInMinutes){ + + Cd cd = new CD(); + cd.title = title; + cd.author = author; + cd.tracks = tracks; + cd.durationInMinutes = durationInMinutes; + cdList.add(cd); +} + +=> 굳이 주석을 달지 않아도 충분한 정보를 제공하는데, 의무감에 의해 주석을 달 경우 혼동이 생길 수 있다. + +3. 주석으로 처리한 코드 + +가장 많이 발생하는 경우가 아닌가 싶다. +주석으로 처리한 코드만큼 지저분한 주석도 없다. + +이유가 있어서 주석 처리했을 거란 생각에 보통 잘 지우지 않는 편인데, 소스 코드에 이런 주석 코드가 점점 쌓이면 정말 더러워진다. + + + // useEffect((e) => { + // async function viewFavoritesData() { + // const res = await axios.get( + // `http://3.38.210.200:8080/myPage/like/${memberInfoId}`, + // { + // withCredentials: true, + // headers: { + // Authorization: `Bearer ${sessionStorage.getItem("user_token")}`, + // }, + // } + // ); + // const _favorData = await res.data.itemList.map((rowData) => ({ + // nft_item_id: rowData.nftItemId, + // created_date: rowData.createdDate, + // profileImg: rowData.profileImg, + // memberId: rowData.memberId, + // nickname: rowData.nickname, + // nftItemImg: rowData.nftItemImg, + // price: rowData.price, + // likeCnt: rowData.likeCnt, + // title: rowData.title, + // view_cnt: rowData.viewCnt, + // status: rowData.status, + // })); + // setFavorData(favorData.concat(_favorData)); + // console.log(_favorData); + // } + // viewFavoritesData(); + // }, []); + + => 실제로 프로젝트에서 코드를 주석으로 처리한 경우가 많다.. + +4. 이력을 기록하는 주석 + +예전에는 모든 모듈 첫 머리에 변경 이력을 작성하곤 했다고 한다. +약간의 관례처럼.. 당시에는 소스 코드 관리 시스템이 없었으니까.. + +하지만 이제는 혼란만 가중할 뿐이므로 완전히 제거하는 편이 좋다. + +아래는 변경 이력을 보여주는 주석이다. + +/** + * 변경 이력 (11-Oct-2001부터) + * -------------------------------- + * 11-Oct-2001 : 클래스를 다시 정리하고 새로운 패키지인 com.jrefinery.date로 옮겼다 (DG); + * 05-Nov-2001 : getDescription() 메서드를 추가했으며 NotableDate class를 제거했다 (DG); + * 12-Nov-2001 : IBD가 setDescription() 메서드를 요구한다 NotableDate 클래스를 없앴다 (DG); + * getFollowingDayOfWeek(), getNearestDayOfWeek()를 변경해 버그를 수정했다 (DG); + * 05-Dec-2001 : SpreadsheetDate 클래스에 존재하는 버그를 수정했다 (DG); + * 29-May-2002 : month 상수를 독자적인 인터페이스로 옮겼다 (MonthConstants) (DG); + */ + +5. HTML 주석 + +소스 코드에서 HTML 주석은 정말 더럽다. +HTML 주석은 주석을 읽기 쉬워야 하는 편집기/IDE에서조차 읽기가 어렵다. + +/** + * 적합성 테스트를 수행하기 위한 과업 + * 이 과업은 적합성 테스트를 수행해 결과를 출력한다. + *

+ * 

+ * 용법:
+ * <taskdef name="execute-fitnesse-tests" classname="fitnesse.ant.ExecuteFitnesseTestsTask" classpathref="classpath" />
+ * 또는
+ * <taskdef classpathref="classpath" resource="tasks.properties" />
+ * 

+ * ...
+ */
+
+ 6. 닫는 괄호에 쓰는 주석
+
+ 많은 프로그래머들은 아래와 같이 닫는 괄호에 특수한 주석을 달아놓을 떄가 있다. 닫는 괄호에 주석을 다는 것 대신 코드를 분리하여 줄이려는 시도를 하는 게 좋다.
+
+ func add(n1:Int,n2:Int,infos:[Int]) {
+    for info in infos {
+        if  n1 <  n2{
+            while infos.isEmpty {
+                
+            }//while
+        }//if
+    }//for
+}
+
+
+
+
+[느낀 점]
+
+내 프로젝트에도 나쁜 주석이 많다는 것을 알게 되었다...
+좋은 주석을 위해....끊임없이 노력해야겠다.

From 3cab4193212a38d726cfa8d562ab07d239272aae Mon Sep 17 00:00:00 2001
From: chamny20 
Date: Mon, 28 Nov 2022 20:45:32 +0900
Subject: [PATCH 2/2] chaemin_remark

---
 remark.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/remark.txt b/remark.txt
index 4e702bb..c14af24 100644
--- a/remark.txt
+++ b/remark.txt
@@ -173,7 +173,7 @@ HTML 주석은 주석을 읽기 쉬워야 하는 편집기/IDE에서조차 읽
 
  6. 닫는 괄호에 쓰는 주석
 
- 많은 프로그래머들은 아래와 같이 닫는 괄호에 특수한 주석을 달아놓을 떄가 있다. 닫는 괄호에 주석을 다는 것 대신 코드를 분리하여 줄이려는 시도를 하는 게 좋다.
+ 많은 프로그래머들은 아래와 같이 닫는 괄호에 특수한 주석을 달아놓을 때가 있다. 닫는 괄호에 주석을 다는 것 대신 코드를 분리하여 줄이려는 시도를 하는 게 좋다.
 
  func add(n1:Int,n2:Int,infos:[Int]) {
     for info in infos {