功能/类注释格式约定 [英] Function/Class Comment Formatting Conventions

问题描述

谁拥有最易读和有用的功能/类注释约定? 我不是在寻找生成文档的东西，而是在考虑采用JavaDoc之类的东西，因为所有信息都在那里.

Who has the most readable and useful function/class commenting convention? I'm not looking for something that generates docs, but I'm considering adopting something like JavaDoc because all the info is there.

/**
 * This function processes data
 * 
 * @param p1 the first piece of data
 * @param p2 the second piece of data
 * @return   true if the processing was successful, else false
 */
function ProcessData(p1, p2){

还是其他手工制作的东西?

or some other hand crafted thing?

/////////////////////////////////
// This function processes data
//
// p1    the first piece of data
// p2    the second piece of data
// returns true if processing was successful, else false
function ProcessData(p1, p2){

对多行中的单行注释是否有合理的论点?

Any reasonable argument for single line comments over multiline?

我想对使用的所有语言应用约定，所以请分享您使用的所有特定于语言或与语言无关的约定！

I'd like to apply a convention to all languages I use, so please share any language-specific or language-agnostic conventions you have!

推荐答案

对于注释样式，我肯定会选择多行，因为这就是它们的用途-整体上看起来更干净.

For the comment style, I would definitely go for multiline, as that's what they are for - it just looks cleaner overall.

对于参数，第一个功能更强大，因为您可以指定每种信息的类型:"@ type name description"和"name description"，这是我通常在C类型语言中看到的.

For the params, the first one is more powerful, as you can specify the type of each information: '@type name description', vs 'name description' and it's what I usually see in C type languages.

这篇关于功能/类注释格式约定的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！