评论风格画廊...发表你的评论风格

我喜欢浏览其他人的代码，看看他们如何评论他们的风格，大多数人使用*和////的混合，当然这一切取决于语言，但我肯定看到了一些好的方法来评论和一些不好的方法。一个编码页面可以真正地与正确的评论结构一起使用，并且使得在没有任何知识的情况下进入项目的人很容易阅读。评论风格画廊...发表你的评论风格

我很好奇看到人们认为什么是最好的方式来设置评论，部门分区等。这可能是HTML，PHP或其他任何事情。

来源

2011-08-04 pfunc

PHP：
我个人使用//为方法/函数内的一切。这是令人讨厌的，如果有人使用/* */，因为它使得更难注释代码块

为了便于记录，我使用了与javadoc非常相似的phpdoc使用。

/** 
* Overall description 
* @keyword - description 
*/

通常是一个很好的规则是，如果你去15-20行没有任何意见，你需要把一些意见，除非代码是真正的自我解释。虽然当时你可能会认为你会记得你的500线功能和它所做的一切，但你经常不会。如果是别人试图进入并理解你的代码，那对他们来说只会更困难！

来源

2011-08-04 13:27:07 afuzzyllama

同样在这里 - 这两个块的评论是必要的，和文件处理 - jsdoc在我的情况。 – danjah

A面节点（快速链接，不是我的）：http://www.heartysoft.com/ninja-coding-code-comments

为什么我不喜欢评论

我试图避免评论我的代码的主要原因是概念自解释代码的。代码应该是自我解释 - 任何人阅读代码应该明白发生了什么（当然，给定一些域名的知识）。依靠评论来解释发生了什么几乎不是一个好主意。代码将比评论更新更频繁。无论你的团队多么警惕，这是必然会发生。充其量，这可能会导致评论稍微过时。在最坏的情况下，陈旧的评论可能完全误导代码实际上在做什么。

我总是试图重构我的代码，以便它不需要任何附加说明。

所以我最终得到的结果只有通常的xDoc注释来自动生成APIDoc。即使这些评论可以在很大程度上自动生成。

在特殊情况下（例如操作系统特定问题），我尝试找到讨论问题并添加链接的公共网站。如果链接在未来的时间中断 - 狗屎发生。

AS3：

/** 
* This is a usual doc comment for a type or property. 
*/ 

/* 
* This is a marker of a particular longer section of code. 
*/ 

// This is a single line comment before a or at end of a line of code.

来源

2011-08-04 13:30:03

尽管我倾向于在更高层次上（抽象类和类似）达成一致，但在较低层次上，我肯定会写评论来解释我期望的事情会经常发生变化。我不认为我的代码像我认为的那样“完全可读”，并且我还假定一些承包商的代码是gunna摇滚起来并且像.. wtf ?!所以快速修复或古怪的代码，我会def。评论它。 – danjah

“总是假设将来负责维护你的代码的人是一个知道你住在哪里的精神病患者......” – Landric

@Jens：代码应该是不言自明的，但是如果你处理的是一个非常大的一段代码？ – 2011-08-04 14:20:17

在AS3中，我用这个：

/** 
* 
* to comment (if necessary) a method or a group of related methods 
* 
*/

，而我用这个：

//

为单行注释。

此外，我通常会插入空的//注释以获得更多的代码readeability。

来源

2011-08-04 14:15:06

评论风格画廊...发表你的评论风格

回答

相关问题