什么是较少恼人：没有源代码文档或坏代码文档？ [英] What is less annoying: no source code documentation or bad code documentation?

问题描述

今天，我和一位同事有一个论点，他的一个评论作为方法的总结。大多数情况下，他没有写任何摘要，但在这种情况下，他添加了一个，这是一个非常糟糕的一个：没有描述该方法是做什么，它假设该方法可能正在做什么。我要补充一点，这段代码不是他自己的，它是遗留代码。

我告诉他，在这种情况下，他应该从来没有做过任何评论，只有在真正检查发生了什么之后，因为有人谁读他的意见作为有效的声明，不会自己检查和拧紧。他可以添加这是一个假设，请自己检查。但他没有。即使没有评论，也会更好，因为开发人员必须检查自己。

我个人对代码文档非常严格。这不意味着我评论每一行代码，但方法，类等摘要是强制性的，并且困难的代码部分的额外行也有帮助。

我必须添加我在一个由10个开发人员组成的团队中工作，没有人为自己编写代码。花费更少的时间在代码文档上意味着其他开发人员花费更多的时间来获得代码的意义。

我甚至不能说如果我不喜欢没有文档少于这种坏文档。但到最后，我想我花更多的时间没有记录比没有良好的记录外部代码。所以...我讨厌两个。 ;）

你觉得怎么样？你不在乎或你在日常工作中看到这些东西吗？

Michael

>

解决方案

看起来有权威性的文件错误比没有文件差。

标记为的投机文档通常比没有文档更好。

Today I had an argument with a colleague about one of his comments as summary of a method. Mostly he is not writing any summaries but in this case he added one and it was a really bad one: It was not described what the method is doing, it assumed what the method maybe is doing. I have to add that this piece of code was not his own, it was legacy code.

I told him that in this case he should have never made any commentary, only after really checking what is happening there, because someone who does read his opinion as valid statement will not check by himself and screw up. He could have add "This is an assumption, please check for yourself." but he didn't. Even if no commentary was there it would be better because then the developer has to check for himself.

Personally I'm very strict on code documentation. That doesn't mean I comment every line of code but method, class, etc summaries are mandatory and additional lines for difficult code parts are helping too.

I have to add that I work in a team of 10 developers where no one writes code only for himself. Spending less time on code documentation means that other developers are spending more time to get the meaning of the code.

I'm not even able to say if I like no documentation less than this kind of bad documentation. But at the end I guess I spend more time with not documented than not good documented foreign code. So... I hate both. ;)

What do you think? You don't care or do you see these things in your daily work too? What is worse for you: no code documentation or bad code documentation?

Thanks!

Michael

解决方案

Incorrect documentation that looks authoritative is worse than no documentation.

Incomplete documentation is better than no documentation.

Speculative documentation that is marked as such is, often, better than no documentation.

这篇关于什么是较少恼人：没有源代码文档或坏代码文档？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！