주석 규칙

1. [필수] 클래스, 클래스 속성 및 클래스 메소드에 대한 설명은 Javadoc 사양을 사용해야 하며 // xxx 메소드는 허용되지 않습니다.

참고: IDE 편집 창에서 Javadoc 모드는 관련 주석을 표시하고 생성된 Javadoc은 해당 주석을 올바르게 출력할 수 있습니다. IDE에서 프로젝트가 메소드를 호출할 때 마우스를 올려 메소드를 표시할 수 있습니다. , 매개변수, 반환 값의 의미는 읽기 효율성을 향상시킵니다.

2. 모든 추상 메소드(인터페이스의 메소드 포함)에는 반환 값, 매개변수 및 예외 설명 외에도 메소드가 수행하는 작업과 구현하는 작업을 표시해야 합니다. . 기능.

참고: 서브클래스 구현 요구사항이나 호출 시 주의사항을 설명해 주세요.

3. [필수] 모든 클래스는 크리에이터 정보를 필수로 입력해야 합니다.

4. [필수] 메서드 내부에 한 줄 주석을 달고, 주석 처리된 문 위에 새 줄을 시작하고 // comment를 사용합니다. 메소드 내 여러 줄 주석

/* */ 주석을 사용하고 코드와 정렬되도록 주의하세요.

5. [필수] 모든 열거 유형 필드에는 각 데이터 항목의 목적을 설명하는 설명이 있어야 합니다.

6. [추천] 어설프게 영어로 댓글을 달기보다는 중국어 댓글을 사용하여 문제를 명확하게 설명하는 것이 좋습니다. 고유명사와 키워드는 영어 원문에 그대로 남을 수 있습니다.

카운터 예: "TCP 연결 시간 초과"는 "전송 제어 프로토콜 연결 시간 초과"로 해석되는데, 이는 이해하기 더 어렵습니다.

7. [권장 사항] 코드 수정 시 주석도 그에 맞게 수정해야 하며, 특히 매개변수, 반환 값, 예외, 핵심 로직 등을 수정해야 합니다.

.

설명: 도로 네트워크 및 내비게이션 소프트웨어 업데이트가 동기화되지 않은 것처럼 코드 및 주석 업데이트도 동기화되지 않습니다. 내비게이션 소프트웨어가 심각하게 지연되면 내비게이션의 의미가 상실됩니다.

8. [참고] 주석 처리된 코드에는 단순히 주석 처리가 아닌 가능한 한 지침을 동반해야 합니다.

참고:

코드를 주석 처리할 때 두 가지 가능성이 있습니다. 1) 이 코드의 논리는 나중에 복원됩니다. 2) 절대 사용하지 마세요. 전자에 코멘트 정보가 없으면 주석을 달게 된 동기를 알기 어렵다. 후자는 직접 삭제하는 것이 좋습니다(코드 웨어하우스는 기록 코드를 저장합니다).

9. [참고] 댓글 요구사항: 첫째, 디자인 아이디어와 코드 로직을 정확하게 반영할 수 있어야 합니다. 둘째, 다른 프로그래머가 코드 뒤에 숨은 정보를 빠르게 이해할 수 있도록 비즈니스 의미를 설명할 수 있어야 합니다. 주석이 전혀 없는 큰 부분은 독자에게 있어서 천국의 책과도 같습니다. 주석은 자신이 읽는 것이기에, 오랜 시간이 지나도 그 당시의 생각을 명확하게 이해할 수 있도록 하는 것입니다. 그들이 당신의 일을 신속하게 이어받을 수 있도록. 10. [참고] 좋은 이름 지정과 코드 구조는 설명이 필요하며, 댓글은 간결하고 정확하며 표현력이 풍부해야 합니다. 극단적인 주석을 피하십시오. 주석이 너무 많고 과도한 경우 코드의 논리가 수정되면 주석을 수정하는 것이 상당한 부담이 됩니다.

카운터 예:

// put elephant into fridge
put(elephant, fridge);

메소드 이름 put 과 두 개의 의미 있는 변수 이름 Elephant 및 Fridge 는 이미 이것이 수행하는 작업을 설명했으며 의미가 명확한 코드에는 추가 주석이 필요하지 않습니다.

11. [참고] 특수댓글 표시는 표시한 사람과 표시한 시간을 표시해 주세요. 적시에 이러한 표시를 처리하고 표시를 스캔하고 해당 표시를 자주 청소하도록 주의를 기울이십시오. 온라인 오류는 때때로 이러한 표시의 코드에서 발생합니다.

1) 할 일 항목(
TODO

) : (사람 표시, 표시 시간, [예상 처리 시간])

구현해야 하지만 아직 구현되지 않은 기능을 나타냅니다. 이것은 실제로 Javadoc 태그입니다. 현재 Javadoc은 아직 구현되지 않았지만 이미 널리 사용되고 있습니다. 클래스, 인터페이스 및 메소드에만 적용할 수 있습니다(Javadoc 태그이기 때문입니다).

2) 오류, 작동 불가(FIXME

): (사람 표시, 시간 표시, [예상 처리 시간])

FIXME를 댓글에 사용하여 잘못되어 작동할 수 없는 특정 코드를 표시하고 필요한 코드를 표시하세요. 시간에 맞춰 수정해야 할 상황입니다.