| English | 의미 |
|---|---|
| comment/ˈkɒment/ | 주석 |
주석은 활성화된 공식을 수선하지 못함
- 가격 100에 대해, 주석이 "10% 할인 후 지급 금액"이라고 하더라도
total = price * 10 / 100;은 10을 계산합니다. 그 설명을 편집하는 것이 식을 90으로 계산하게 만들지는 않습니다. - 전체 숫자 예제에서 의도한 결제액을 계산하도록 활성화된 식을
price * 90 / 100으로 변경하십시오. 주석은 의도된 정책을 드러낼 수 있으나, 코드가 이를 구현했는지 확인하십시오.
코드에서 제외되는 텍스트 식별
//은 줄바꿈까지 이어지는 주석을 시작합니다./*은 다음*/까지 이어지는 블록 주석을 시작하며, 블록 주석은 중첩되지 않습니다. 문자열 리터럴 내의 경계 기호는 텍스트이므로"https://example.com"은 주석을 시작하지 않습니다.- 주석 텍스트는 Java 문문으로 실행되지 않습니다. 별도의 설명을 추가하면 활성화된 식은 그대로이지만, 활성화된 할당문 앞에
//을 배치则该 할당은 컴파일된 코드에서 제거되고 동작이 변경될 수 있습니다.
Javadoc 태그를 별개의 줄에 배치
- 선언 바로 전에 있는
/** ... */문서화 주석은 Javadoc에 의해 처리될 수 있습니다. 요약은 연산을 설명하며,@param과@return같은 블록 태그는 선택적 공백과*이후 자체 줄에서 시작합니다. - 아래 완전한 클래스는 음수가 아닌 반지름을 문서화하고 원의 면적을 반환합니다. 태그는 입력, 출력 및 거절된 입력을 설명하며, 주석만으로는 전제조건을 강제하지 않으므로 메서드는 음수 반지름을 명시적으로 확인합니다.
/** Circle-area calculations for finite radii. */
public class AreaDoc {
/**
* Returns the area of a circle for a finite radius.
* @param r the non-negative radius
* @return the area in squared radius units
* @throws IllegalArgumentException if r is negative
*/
public static double area(double r) {
if (r < 0) {
throw new IllegalArgumentException("Negative radius");
}
return Math.PI * r * r;
}
}
Javadoc에서 @param은 같은 줄의 요약 텍스트 뒤에 포함될 때 블록 태그로 인식됩니다.
난이도 1/5 · 100 코인 + 오늘 첫 완료 시 소액 보너스
블록 태그는 선택적 공백과 선택적 앞쪽 별표가 있는 후 다음 줄부터 시작해야 합니다. 표시된 다중 줄 주석을 사용하십시오.
읽을 수 없는 결정을 설명하세요
- 유용한 할인 주석은 “결제 가격은 90%입니다; 이 연습에서는 정수 가격을 사용합니다”라고 명시할 수 있습니다. 이는 정책과 가정을 설명하지만,
// multiply by 90는 단순히 연산을 반복할 뿐입니다. - 본문이 짧더라도-public-메서드의 요약은 유익합니다. 호출자는 구현을 분석하지 않고도 계약이 필요합니다. 모든 서술형 주석이 불필요하다고 선언하기보다 누락된 맥락을 제공하는 설명을 선호하십시오.
Java 프로그램이 실행될 때 주석들은...
난이도 1/5 · 100 코인 + 오늘 첫 완료 시 소액 보너스
주석은 인간을 위한 것 — Java는 무시합니다.
Java에서 단일 줄 주석을 시작하는 것은?
난이도 1/5 · 100 코인 + 오늘 첫 완료 시 소액 보너스
//는 줄 끝까지 이어지며; /* */는 블록입니다.
어떤 주석 스타일이 도구에서 API 문서로 변환되나요?
난이도 1/5 · 100 코인 + 오늘 첫 완료 시 소액 보너스
Javadoc /** */ with @param/@return이 API 문서를 생성함.
변경되지 않은 활성화된 수식 옆에 설명 주석을 추가하면 해당 수식의 계산이 수정됩니다.
난이도 1/5 · 100 코인 + 오늘 첫 완료 시 소액 보너스
거짓: 설명 주석은 문장이 아닙니다. 문장을 주석 처리하면 동작이 변경될 수 있으나, 이는 어떤 코드가 활성화되는지를 바꾸는 것입니다.
좋은 주석은 code가 명확히 하는 것을 재현하기보다 WHY를 설명합니다.
난이도 1/5 · 100 코인 + 오늘 첫 완료 시 소액 보너스
명백한 것 대신 의도를 주석으로 남기십시오.
구현에 대한 문서화 확인
- 주석이 음의 반지름을 거부한다고 약속하지만 보호 장치가 삭제된 경우를 가정해 봅시다. 문서화는 여전히 성공적으로 생성되지만 거짓이 되었으므로, 일반 반지름뿐만 아니라 음의 입력도 테스트해야 합니다.
- 행동이 변경되면 구현, 검사 사항 및 문서화를 함께 업데이트하십시오. API 페이지 생성은 문서화 구文을 검증할 뿐이며, 그 안의 모든 주장의 진실을 검증하는 것은 아닙니다.
/** Returns an area. @param r radius @return area */는 블록 태그를 줄 시작 위치에 배치하지 않습니다. 위의 다중 줄 형식을 사용하고 생성된 매개변수 및 반환 섹션을 검토하십시오. 일반적인 설명 주 executable 수치는 실행 가능한 수치가 아닙니다.
유용한 주석인가?
좋은 주석은 명백한 것을 설명하기보다 의도를 설명합니다. 각각을 분류하십시오.
주석 처리된 할당 예측
int x = 1;로 시작하십시오. 활성화된x = 5;에서 x를 출력하면 5이 나옵니다. 해당 줄을// x = 5;으로 교체하면 1이 출력됩니다. 활성화된 문장을 바꾸는 것은 변함없는 문장 옆에 주석을 추가하는 것과 다릅니다.- 세 가지 질문을 개별적으로 검토하십시오: 활성화된 계산이 올바른지, 주석이 이를 정확히 설명하는지, Javadoc 태그가 의도된 섹션으로 파싱되었는지입니다. 성공적인 컴파일은 이 세 가지 모두에 답하지 않습니다.
주석은 코드를 읽자에게 설명합니다. 구분符는 문장을 제외할 수 있지만, 활성화된 코드 옆의 주석은 계산을 수정하지 못합니다. Javadoc 블록 태그는 별도의 줄에서 시작해야 하며, 문서화된 계약은 구현과 일관성을 유지해야 합니다.
For a price of 100, type the amount paid after a ten percent discount.
난이도 1/5 · 100 코인 + 오늘 첫 완료 시 소액 보너스
The intended payment is 100−10=90. The misleading comment does not make the original expression calculate 90.
int x = 1; 다음 줄에 // x = 5;가 있습니다. 출력되는 x의 값은 무엇입니까?
난이도 2/5 · 140 코인 + 오늘 첫 완료 시 소액 보너스
5에 대한 할당은 단일 줄 주석으로 제외되므로, x는 1을 유지합니다.