如何在编写javadoc时足够具体 [英] How to be Specific enough in writing javadoc
问题描述
我有关于编写标准javadoc注释的问题。
他们要求我们尽可能具体，并使用谓词来描述代码，但是如果我在注释中写了一个变量 d，但未在代码中指出，那会带来问题吗？ p>
再次，我问这个问题是因为我感到困惑，我的老师对注释代码严格。
/ **
*找到2之间的大公约数。
*
* @param a number1
* @param b number2
* @return（\max d;; a％d == 0&& b％d == 0）
** /
public static int GCD（int a，int b）{
if（b == 0）{
返回a;
}
返回GCD（b，a％b）;
}
要编写文档，让自己扮演使用您方法的人的角色。作为您使用该方法的用户，只要我能获得正确的结果，我都不在乎是否要飞向月球并向外星人询问结果。
因此，通常不应将实现细节包含在文档中（如果您在实现中具有名称为 d的变量与文档无关紧要）。您应该能够重构或更改内部详细信息，而不会影响您的文档。
示例示例会影响以下事实：
- 行为（即线程安全）
- 性能（有人认为飞向月球会影响性能；））
- 安全性
- ...
那么用户感兴趣的是什么？
- 该方法的作用-用户可能与您所掌握的知识不尽相同，因此请您多加解释（例如，并非每个人都知道Gli是）
- 应该期望什么参数，它们是什么以及它们的外观如何（在您的示例中，数字为正数和整数很重要，在您的情况下为 a并且 b可能为0-但并非GCD的每个定义都包含0作为有效值）
- 我期望返回什么，在边界情况下返回什么（例如a和b = 0）
- 例外情况是什么我需要预料一下，什么时候抛出它们
所以您的方法的文档可能像这样：
/ **
*返回两个给定正整数的最大公约数。
*< p>
*最大公约数（GCD）是最大整数，
*是两个给定数字的因数。 < br>
*数字具有以下属性，即为GCD：[...] //在此处添加属性
*< p>
*示例：20和16的GCD为4
*
* @param a
*第一个正整数，可能为0
* @param b
*第二个正整数，可以为0 $ b $ b * @返回给定数字的最大公约数。如果a和b为0，则返回0。
*如果一个为0，则返回非0值。
** /
public static int findGreatCommonDivisor（int，int b）
{
if（b == 0）
{
返回a;
}
返回findGreatCommonDivisor（b，a％b）;
}
I have question related to writing standard javadoc comments. They ask us to be as specific as possible and use predicates to describe the code, but if I have a variable "d" written in my comment, but not indicated in my code, would that pose a problem?
Once again, I ask this question because I get confused and my teacher is strict on commenting code.
/**
* Find the great common divisor between a 2 number.
*
* @param a number1
* @param b number2
* @return (\max d; ; a % d == 0 && b % d == 0)
**/
public static int GCD(int a, int b) {
if (b == 0) {
return a;
}
return GCD(b, a % b);
}
To write the documentation you have to put yourself in the role of the person that uses your method. As a user of your method I don't care if you fly to the moon and ask an alien for the result as long as I get reliable the correct result.
So normally implementation details should not be included into the documentation (if you have a variable with the name "d" in your implementation should not matter to your documentation). You should be able to refactor or change internal details without it affecting your documentation.
Examples for exceptions are facts that affect:
- behaviour (i.e. thread safety)
- performance (one could argue that flying to the moon would affect the performance ;) )
- security
- ...
So what does interest the user?
- what the method does - the user likely has not the same knowledge as you so explain a lot (for example not every one knows what a GCD is)
- what parameters are expected, what they are and how they should look like (in your example its important that the numbers are positive and whole numbers, in your case "a" and "b" may be 0 - but not every definition of the GCD has 0 as a valid value included)
- what can I expect to be returned, what is returned in border cases (like a and b =0)
- what exceptions do I need to expect and when are they thrown
So a documentation for your method could look like:
/**
* Returns the greatest common divisor of the two given positive whole numbers.
* <p>
* The greatest common divisor (GCD) is the largest whole number that
* is a factor of both of the given numbers. <br>
* A number is a GCD if it has the following properties: [...] //add the properties here
* <p>
* Example: the GCD of 20 and 16 is 4
*
* @param a
* the first positive whole number, may be 0
* @param b
* the second positive whole number, may be 0
* @return the greatest common divisor of the given numbers. Returns 0 if a and b are 0.
* Returns the not 0 number if one is 0.
**/
public static int findGreatCommonDivisor( int a, int b )
{
if ( b == 0 )
{
return a;
}
return findGreatCommonDivisor( b, a % b );
}
这篇关于如何在编写javadoc时足够具体的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
