你的个人态度/评论是什么？ [英] What is your personal approach/take on commenting?
问题描述
重复
工作有一些事情要说评论，对我有趣（见下文）。
我不向代码添加注释，除非
它是一个简单的标题或者有一个
平台的错误或一个必要的
的工作，这是不明显的代码
可以更改和评论可能会变成
误导。代码应该< br>
在使用
描述性名称及其逻辑
组织时自我记录 - 及其解决方案
应该是最简洁的方法
来执行一个给定的任务如果
程序员不能通过只读代码来告诉程序
，那么
他就不能改变它了。 >
注释往往是一个拐杖为
编写复杂的东西或
非显而易见的 - 我的目标是总是
编写干净和简单的代码。
我想有几个营地，当它
来评论，
enterprisey类型谁认为他们是
编写一个API和一些大的
代码库，将用于
代来，
工匠类程序员认为
代码说明它比
更清楚可以和新手写
冗长/不清楚的代码，以便需要
给自己留下注释，为什么
他们做了什么。
自我文档化代码理论有一个悲剧性的缺陷。是的，阅读代码会告诉你是什么。但是，代码不能告诉你应该做什么。
我认为可以安全地说，所有的错误都是由于代码不是做它应该做什么:)。因此，如果我们添加一些关键的注释，为维护者提供足够的信息来知道一段代码应该做什么，那么我们就给了他们修复很多错误的能力。
这使我们有多少评论放入的问题。如果你提出太多评论，事情变得乏味维护和评论将不可避免地与代码过时。
我发现常规评论在以下地方最有用：
1）在.h或.cpp文件顶部的简要描述，用于解释类的目的类。这有助于给维护者一个快速的概述，而不必筛选所有的代码。
2）在执行一个非平凡函数之前的注释块解释的目的它详细描述了它的预期输入，潜在输出以及调用函数时的任何奇怪。这可以使未来的维护者不必破译整个函数来计算这些东西。
除此之外，我倾向于评论任何可能对某人造成混乱或奇怪的东西。例如：这个数组是基于1而不是基于0因为blah blah。
写得很好，很好放置的评论是无价的。糟糕的评论往往比没有评论。对我来说，缺少任何意见表示懒惰和/或代码作者的傲慢。不管你对代码的作用有多么明显，或者你的代码是多么奇妙，这是一个具有挑战性的任务，进入一个代码冷的身体，弄清楚它是怎么回事。好的评论可以使一个差异的世界，让人们加快现有的代码。
Duplicate
A Developer I work with had some things to say about commenting that were interesting to me (see below). What is your personal approach/take on commenting?
"I don't add comments to code unless its a simple heading or there's a
platform-bug or a necessary work-around that isn't obvious. Code can change and comments may become misleading. Code should be
self-documenting in its use of descriptive names and its logical
organization - and its solutions should be the cleanest/simplest way
to perform a given task. If a programmer can't tell what a program
does by only reading the code, then he's not ready to alter it.
Commenting tends to be a crutch for writing something complex or
non-obvious - my goal is to always write clean and simple code.""I think there a few camps when it comes to commenting, the enterprisey-type who think they're writing an API and some grand code-library that will be used for generations to come, the craftsman-like programmer that thinks code says what it does clearer than a comment could, and novices that write verbose/unclear code so as to need to leave notes to themselves as to why they did something."
There's a tragic flaw with the "self-documenting code" theory. Yes, reading the code will tell you exactly what it is doing. However, the code is incapable of telling you what it's supposed to be doing.
I think it's safe to say that all bugs are caused when code is not doing what it's supposed to be doing :). So if we add some key comments to provide maintainers with enough information to know what a piece of code is supposed to be doing, then we have given them the ability to fix a whole lot of bugs.
That leaves us with the question of how many comments to put in. If you put in too many comments, things become tedious to maintain and the comments will inevitably be out of date with the code. If you put in too few, then they're not particularly useful.
I've found regular comments to be most useful in the following places:
1) A brief description at the top of a .h or .cpp file for a class explaining the purpose of the class. This helps give maintainers a quick overview without having to sift through all of the code.
2) A comment block before the implementation of a non-trivial function explaining the purpose of it and detailing its expected inputs, potential outputs, and any oddities to expect when calling the function. This saves future maintainers from having to decipher entire functions to figure these things out.
Other than that, I tend to comment anything that might appear confusing or odd to someone. For example: "This array is 1 based instead of 0 based because of blah blah".
Well written, well placed comments are invaluable. Bad comments are often worse than no comments. To me, lack of any comments at all indicates laziness and/or arrogance on the part of the author of the code. No matter how obvious it is to you what the code is doing or how fantastic your code is, it's a challenging task to come into a body of code cold and figure out what the heck is going on. Well done comments can make a world of difference getting someone up to speed on existing code.
这篇关于你的个人态度/评论是什么？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
