代码注释要点(Tips to Comment Your Code)
来源:互联网 发布:淘宝促销活动快捷短语 编辑:程序博客网 时间:2024/05/18 03:21
Tips to Comment Your Code
Break code blocks into multiple “paragraphs” that each perform a single task, then add a comment at the beginning of each block to instruct the reader on what is about to happen.// Check that all data records
// are correct
foreach (Record record in records)
{
if (rec.checkStatus()==Status.OK)
{
. . .
}
}
// Now we begin to perform
// transactions
Context ctx = new ApplicationContext();
ctx.BeginTransaction();
. . .
For multiple lines of code with trailing comments, align the comments so they will be easy to read.
const MAX_ITEMS = 10; //
maximum number of packets
const MASK = 0x1F; // m
ask bit TCP
Some developers use tabs to align comments, while others use spaces. Because tab stops can vary among editors and IDEs, the best approach is to use spaces.
Avoid obvious comments such as:
if (a == 5) // if a equals 5
counter = 0; // set the counter to zero
This wastes your time writing needless comments and distracts the reader with details that can be easily deduced from the code.
When working on code as a team, adopt a consistent set of tags to communicate among programmers. For example, many teams use a “TODO:” tag to indicate a section of code that requires additional work:
int Estimate(int x, int y)
{
// TODO: implement the calculations
return 0;
}
Tag comments don’t explain code; rather they seek attention or deliver a message. But if you use this technique, remember to follow up and actually do what the message is asking.
Add comments while you write code and it’s fresh in your memory. If you leave comments until the end, it will take you twice as long, if you do it at all. “I have no time to comment,” “I’m in a hurry,” and “The project is delayed” are all simply excuses to avoid documenting your code. Some developers believe you should write comments before code as a way to plan out your ultimate solution. For example:public void ProcessOrder()
{
//
Make sure the products are available
//
Check that the customer is valid
//
Send the order to the store
//
Generate bill
}
When it comes to commenting code, think not only about the developers who will maintain your code in the future, but also think about yourself. In the words of the great Phil Haack:
“As soon as a line of code is laid on the screen, you’re in maintenance mode on that piece of code.”
As a result, we ourselves will be the first beneficiaries (or victims) of our good (or bad) comments.
One of the basic principles for many developers: Let your code speak for itself. Although one suspects this movement is led by programmers who do not like to write comments, it is true that self-explanatory code can go a long way toward making code that’s easier to understand and can even render comments unnecessary. For example, the code in my Fluid Interfaces article shows how clear self-explanatory code can be:
Calculator calc = new Calculator();
calc.Set(0);
calc.Add(10);
calc.Multiply(2);
calc.Subtract(4);
Console.WriteLine( "Result: {0}", calc.Get() );
In this example, comments are not needed and would likely violate tip #4. To facilitate readable code, you might consider using proper names (as described in the classic Ottinger’s Rules), ensure correct indentation, and adopt coding style guides. Failure to comply with this tip may result in comments that seem to apologize for bad code.
其他链接:
http://particletree.com/features/successful-strategies-for-commenting-code/
http://freshmeat.net/articles/you-are-expected-to-understand-this
http://www.google.com/search?q=coding+style+guides&ie=utf-8&oe=utf-8&aq=t&rls=org.mozilla:en-US:official&client=firefox-a
- 代码注释要点(Tips to Comment Your Code)
- 13 Tips to Comment Your Code (转)
- 注释你的代码 Commenting your code
- 注释还是不注释(To comment or not to comment )
- (add comment to table or column,and add comment to ddl script) erwin为ddl script 脚本添加表或字段的注释(导出注释)(comment)
- 代码注释(Code comments)
- 代码注入(Inject your code to a Portable Executable file)
- 40 Tips for optimizing your php Code 优化PHP代码的40条建议
- PL/SQL 注释(Comment)
- C# 注释(Comment)规范
- 40 Tips for optimizing your php Code
- 代码注释(code comments)
- Tips To Warm Your Hands & Feet [Health Tips]
- 【Oracle】添加注释(COMMENT ON)
- 缩减代码和资源(Shrink Your Code and Resources)
- 缩减代码和资源(Shrink Your Code and Resources)
- 缩减代码和资源(Shrink Your Code and Resources)
- 注释与反注释Comment/Uncomment selected code in Visual C++
- struts result type
- 我们不要冷冰冰的黑色长方体
- java构造函数
- Harris角点检测算法优化(有matlab源代码)
- 位图——Bitmap和BitmapData(一)
- 代码注释要点(Tips to Comment Your Code)
- mysql无法启动
- C++ primer 习题练习:3.17
- 优化的Harris角点检测算法的MATLAB实现
- POJ 2082 Terrible Sets
- 出差了,住哪网最合适?
- 集成 Flex, Spring, Hibernate 构建应用程序
- 头文件string.h中的函数及使用方法
- 内存管理一