Piz*_*rog 40 java grammar javadoc
我有一个名为的班级Identity.在我的javadoc评论中,我将其称为复数形式.我可以想到两个解决方案:更改<code>Identities</code>或<code>Identity</code>s 的引用.这些都不正确,我想知道是否有更好的解决方案.
这是一个清晰的例子:
/**
* Returns an <code>IdentityBank</code> of <code>Identity</code>s with the given sex.
*/
要么
/**
* Returns an <code>IdentityBank</code> of <code>Identities</code> with the given sex.
*/
Col*_*ica 42
听起来你想在这里做两件事:使用良好的语法,但也要使用你的类的文字,逐字名称,以便你的javadoc用户可以查找它们.
使用复数时可以做的一件事是使用短语"X实例".所以使用你的例子,你可以把:
/**
* Returns an <code>IdentityBank</code> of <code>Identity</code> instances with the given sex.
*/
如果需要指定多个值类型(本身没有实例),则可以使用"X值".例如,您可以说"返回int值列表".其他可接受的名称可能是"记录","注释","条目","通知",或者如@ Marco13所述,"对象".
您应该避免在框架,系统或应用程序中使用与现有术语或类名冲突的术语,除非您使用的术语已经使用过.例如,除非您在文件系统中引用文字文件,否则不要说"返回案例文件列表".使用它来引用文件的业务规则概念会增加混淆的可能性.因此而考虑避免的其他术语可能是"数据库","表"(除非引用数据库中的实际表或它们的抽象或表示),"页面","表单","表单","驱动程序" ,"端口","窗口","列表","堆","堆栈","应用程序","例外"(除非它们是Throwable),"引脚"和"总线".
同样,如果任何合理的名词符合代码的业务规则并且可以理解,那么任何合理的名词都是有用的.您可以执行以下任何操作:
Boh*_*ian 28
使用"...(s)"样式复数标签,与{@link}班级:
/**
* Returns an {@link IdentityBank} of {@link Identity Identity(s)} with the given sex.
*/
这将呈现为:
返回
IdentityBank的Identity(s)与给定的性.
阅读起来既简单又自然,而且显而易见,清晰明白.
{@link}无论如何你应该使用课程.它负责<code>样式格式化,并提供实际类的HTML链接.
您可以在链接后编码"(s)" ,即{@link Identity}(s)意味着完全传统的用法{@link},但是中间字体会有字体更改:
返回
IdentityBank的Identity与给定的性别(S).
恕我直言会降低清晰度并可能导致混淆.
当我看到问题标题时,我想知道:在5分钟之后这怎么可能没有被关闭为"主要基于意见"？但我认为这是一个重要的问题,我已经在这个痛苦太多,最终来的结论是,有可能是不同的(目标,即不是基于观点的!)论据,不同的选择-所以这里有我的两分钱:
使用类名Customer和Identity示例,有不同的选项,将呈现如下:
使用不同字体的"s"会降低可读性.错误的复数"身份"是值得怀疑的.
乍一看,这看起来很不错.但它有一个严重的缺点:通常的做法是s为包含工厂方法的类附加类名!例如,按照Customer惯例,将调用包含对象的工厂方法的类Customers.像这样的JavaDoc ......:
显然是令人困惑:该链接不会导致你可能期望从您点击名称的文档.
我通常应用的解决方案(我在上面讨论了方法2的缺点时使用过它):
是的,它可能听起来有点不自然,但我认为它是最好的权衡:名称Identity是可读的,很明显它是一个类名,并且这个类的名称是明确的Identity.
旁注:我通常将名称插入为{@link ...}.由于Eclipse中的自动完成,这很方便,因为它可以显着简化浏览生成的JavaDocs.我建议{@link ...}至少在文档块中出现类名时第一次使用.<code>...</code>可以使用进一步的外观.