API 문서 및 "값 제한":일치합니까?

Question

API 문서(예: '공용 함수의 javadoc')에서 "값 제한"에 대한 설명과 기존 문서를 자주 보시나요?

메모: 나는 그것에 대해 말하는 것이 아닙니다 코드 내의 주석

"값 제한"이란 다음을 의미합니다.

• 매개변수가 null 값(또는 빈 문자열 또는...)을 지원할 수 있습니까?
• '반환 값'은 null이 될 수 있거나 결코 null이 되지 않도록 보장됩니까(또는 "비어 있을" 수 있거나...)?

견본:

내가 자주 보는 것은 (소스 코드에 접근하지 않고도) 다음과 같습니다:

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp
 * @return array of reader names
 */
 String[] getReaderNames(final String aReaderNameRegexp);

내가 무엇을 보고 싶다 다음과 같습니다:

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp 
 * (can be null or empty)
 * @return array of reader names 
 * (null if Report has not yet been published, 
 *  empty array if no reader match criteria, 
 *  reader names array matching regexp, or all readers if regexp is null or empty)
 */
 String[] getReaderNames(final String aReaderNameRegexp);

내 요점은 다음과 같습니다.

getReaderNames() 함수가 포함된 라이브러리를 사용할 때, 그것이 무엇을 하는지 추측하기 위해 API 문서를 읽을 필요조차 없는 경우가 많습니다.하지만 확실히 해야겠어 사용 방법.

이 기능을 사용할 때 내가 걱정하는 유일한 점은 다음과 같습니다.매개변수와 반환값 측면에서 무엇을 기대해야 합니까?매개변수를 안전하게 설정하고 반환 값을 안전하게 테스트하기 위해 알아야 할 것은 이것이 전부입니다. 그러나 API 문서에서는 그런 종류의 정보를 거의 볼 수 없습니다.

편집하다:

이는 사용량에 영향을 줄 수 있습니다. 확인되거나 확인되지 않은 예외.

어떻게 생각하나요 ?값 제한과 API가 함께 속합니까?

Answer 1

내 생각엔 그들은 ~할 수 있다 함께 속하지만 반드시 그럴 필요는 없음 가지다 함께 속하기 위해.귀하의 시나리오에서는 생성된 API 문서 및 intellisense(언어/IDE에서 지원하는 경우)에 표시되는 방식으로 제한이 문서화되어 있는 것이 타당해 보입니다.

제 생각엔 언어에 따라서도 달라지는 것 같아요.예를 들어, Ada에는 "제한된 정수"인 기본 데이터 유형이 있습니다. 여기서 정수 변수를 정의하고 해당 변수가 특정 숫자 범위 내에만(항상) 있음을 명시적으로 나타냅니다.이 경우 데이터 유형 자체가 제한 사항을 나타냅니다.API 문서와 Intellisense를 통해 계속 표시되고 검색 가능해야 하지만 개발자가 주석에서 지정해야 하는 것은 아닙니다.

그러나 Java 및 C#과 같은 언어에는 이러한 유형의 제한된 정수가 없으므로 개발자는 공개 문서의 일부가 되어야 하는 정보인 경우 주석에서 이를 지정해야 합니다.

Answer 2

나는 이러한 종류의 경계 조건이 API에 가장 확실하게 속한다고 생각합니다.그러나 나는 한 단계 더 나아가 해당 null 값이 무엇을 의미하는지 표시할 것입니다(종종 그렇게 합니다).예외가 발생함을 나타내거나 경계 값이 전달될 때 예상되는 결과가 무엇인지 설명합니다.

항상 이렇게 해야 한다는 것을 기억하기는 어렵지만 해당 클래스의 사용자에게는 좋은 일입니다.메서드가 변경하는 계약(예: null 값이 허용되지 않도록 변경되는 경우)을 유지하는 것도 어렵습니다.메소드의 의미를 변경할 때 문서를 업데이트하기 위해 부지런히 노력해야 합니다.

Answer 3

질문 1

API 문서(예: '공용 함수의 javadoc' 등)에서 "값 제한"에 대한 설명과 기존 문서를 자주 보시나요?

거의 없다.

질문 2

이 기능을 사용할 때 내가 걱정하는 유일한 점은 다음과 같습니다.매개변수와 반환값 측면에서 무엇을 기대해야 합니까?매개변수를 안전하게 설정하고 반환 값을 안전하게 테스트하기 위해 알아야 할 것은 이것이 전부입니다. 그러나 API 문서에서는 그런 종류의 정보를 거의 볼 수 없습니다.

함수를 제대로 사용하지 않으면 RuntimeException 메소드 또는 RuntimeException 프로그램의 다른 (때로는 아주 먼) 부분에서.

다음과 같은 댓글 @param aReaderNameRegexp filter in order to ... (can be null or empty) 구현하는 방법인 것 같아요 계약에 의한 디자인 내면의 인간 언어로 Javadoc.

계약에 따른 설계를 시행하기 위해 Javadoc을 사용하는 방법은 다음과 같습니다. iContract, 이제 부활했습니다 JcontractS, 이를 통해 지정할 수 있습니다. 불변, 전제 조건, 사후 조건, 인간의 언어에 비해 더 형식화된 방식으로.

질문 3

이는 확인되거나 확인되지 않은 예외의 사용 여부에 영향을 미칠 수 있습니다.어떻게 생각하나요 ?값 제한과 API가 함께 속합니까?

Java 언어에는 계약에 따른 설계 기능이 없으므로 다음을 사용하고 싶을 수도 있습니다. Execption 그러나 나는 당신이 알아야 할 사실에 동의합니다 확인된 예외와 확인되지 않은 예외를 선택하는 경우.아마도 선택하지 않은 상태로 사용할 수도 있습니다. IllegalArgumentException, IllegalStateException, 또는 단위 테스트를 사용할 수도 있지만 주요 문제는 그러한 코드가 계약에 의한 설계에 관한 것이며 너무 가볍게 변경하기 전에 계약으로 간주되어야 함을 다른 프로그래머에게 전달하는 방법입니다.

Answer 4

나는 그들이 그렇다고 생각하며 항상 헤더 파일(C++)에 그에 따라 주석을 배치했습니다.

유효한 입력/출력/반환 주석 외에도 함수에서 발생할 가능성이 있는 예외가 무엇인지도 기록합니다(종종 반환 값을 사용하여 값을 반환하고 싶기 때문에 오류 코드보다 예외를 선호합니다).

//File:
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);

Answer 5

@파이어랜서:오른쪽!예외에 대해 잊어버렸지만, 특히 이 공개 메서드에서 발생할 수 있는 확인되지 않은 '런타임' 예외에 대해 언급하고 싶습니다.

@마이크 스톤:

메소드의 의미를 변경할 때 문서를 업데이트하기 위해 부지런히 노력해야 합니다.

음 정말 그랬으면 좋겠다 공개 API 문서 최소한 기능 계약에 영향을 미치는 변경 사항이 발생할 때마다 업데이트됩니다.그렇지 않은 경우 해당 API 문서가 완전히 삭제될 수 있습니다.

당신의 생각에 음식을 추가하기 위해 (@Scott Dorman과 함께) 우연히 발견했습니다. Java7 주석의 미래

그게 무슨 뜻이에요?문서에 있는 것보다 특정 '경계 조건'은 API 자체에서 더 나아야 하며 컴파일 시 적절한 '어설션' 생성 코드와 함께 자동으로 사용되어야 합니다.

이렇게 하면 API에 '@CheckForNull'이 있는 경우 함수 작성자가 이를 문서화하지 않고 빠져나갈 수도 있습니다!그리고 의미 체계가 변경되면 해당 API는 해당 변경 사항을 반영합니다(예: '더 이상 @CheckForNull'이 없음).

이러한 종류의 접근 방식은 '경계 조건'에 대한 문서화가 필수 관행이 아니라 추가 보너스임을 시사합니다.

그러나 이는 함수 반환 개체의 특수 값을 다루지 않습니다.이를 위해 완벽한 여전히 문서가 필요합니다.