Question

我已经在我的第一个编程工作大约8个月了，到目前为止我已经学到了不可思议的数量。

不幸的是，我是一家内部应用程序的小型初创公司的唯一开发人员。

有史以来第一次，当我离开这份工作时，我会把我的一些项目交给其他人。我已经彻底记录了我的所有项目（至少我是这么认为的），但我仍然对其他人阅读我的代码感到紧张。

例如，我总是这样做。

for (int i = 0; i < blah.length; i++)
{
//Do stuff
}

我应该将'i'命名为描述性的吗？它只是一个临时变量，并且只存在于该循环中，并且看起来循环对“i”的作用非常明显。

这只是一个例子。另一个是我以不同的方式命名变量...除了使用下划线启动所有私有成员之外，我并不真正符合命名标准。

是否有任何资源可以告诉我如何让下一位开发人员更容易？这类事物有标准吗？

Answer 1

Steve McConnell的

Code Complete是一个很好的地方，可以开始寻找你的问题的答案，还有很多你还没有提出但很快就会这样做。

Answer 2

如果您已完成以下任务，那么将有助于缓解替代者的痛苦：

制作一份架构文档，显示软件的整体结构以及与哪些部分进行交互。
记录每个成员变量/函数/类以指示它们的作用（而不是它们是如何做的）。
编写并记录一些测试，这些测试显示您的程序如何运作以及您希望以预期的方式使用它们。确保记录任何示例数据，以便您的替换人员可以重新运行测试，以了解应该如何工作。
确保您的代码符合标准。即使它不是传统的代码，至少与自身一致的代码也会更容易理解。
如果您对此感到满意，请留下一些联系方式，以便接管的家伙或女士如果真的被卡住，至少可以发电子邮件或给您打电话。我已经为各种项目/工作做了这个。回答这个奇怪的问题并不需要很长时间，但它可以轻松地挽救那些在很长一段时间内继承你的代码库的倾注者。

如果您想要遵守编码标准，a relevant post here on SO会有一些建议。

Answer 3

除了“实际工作”之外（前三个答案还不错），请记住，我们（程序员）是一群傲慢的（而且几乎无知的）怪人;

无论你多么努力地编写好的（并且记录良好的）代码或你应用了多少语法糖：对于新人来说，你的代码总是会“吮吸”（至少在某种程度上），因为他没写。

对于您的示例（使用i for循环），它只是一个本地循环变量。我对你自己不会太努力。只要代码几乎是自我解释的，他就必须进行管理。

Answer 4

变量i中的变量被认为是一种特殊的命名案例。与j，k和l一起，i被充分理解为用于循环的临时“计数器”变量。只要您的使用是一致的，这不会成为问题。

以下是一些可以使代码更易于理解的好规则：

保持一致：确保您的变量命名约定和设计一致。如果经常为循环创建临时变量，它们总是被称为i吗？您是否在其他任何地方使用i来表示不同的内容？一致性意味着代码中存在逻辑模式。模式很容易上传和跟随。
自己解释：确保评论解释为什么您正在做某事，而不是您正在做的事情。像// Loop over array这样的评论无济于事;任何人都可以阅读你的代码并看到你正在执行一个循环。他们想知道的是你为什么要这样做。
记录您的课程：为每个课程，界面，成员，财产的目的提供一些文档，即使它只是一行解释，在尝试理解组件时是一个巨大的帮助一个应用程序。如果在Visual Studio中打开XML注释，则每次忘记添加每个成员的最小摘要时，它都会生成警告。这些评论还有智能感知支持的附加功能，使您的代码更易于使用。

如果您可以说您的代码遵循这些准则，我很乐意继承您的代码。坦率地说，我还没有得到一个代码库，甚至是一个这些建议，但我编写自己的代码，试图让thenextguy的工作变得更加容易。

Answer 5

我知道有两种工具可以帮到你很多。 StyleCop和FxCop。按照链接了解这些工具的全部内容。使用这些工具的最大好处是您不必手动完成代码，这无疑需要很长时间。

Answer 6

我可以从经验中告诉你：其他人不会写出漂亮的代码。实际上，如果您的代码以某种方式记录，它已经比平均值好得多。

不要紧张。有数百种方法可以写同样的东西。每个开发人员都认为他的方式是最好的。 恕我直言，关于编码风格唯一重要的是一致性。因此，如果你“总是做这种事情”，你就会有一致的代码。

Answer 7

这个特殊的结构是常见的，'i'在这里很好。

至于另一个例子，这是主观的，只要你在约定中保持一致，你应该没事。

主要是：坚持

编辑：至于参考，这里有一个你可以使用：

Code Name Convention Reference

Answer 8

这应该是显而易见的，但要确保每个生产组件都具有易于获得的源代码，并且处于可编译状态。确保编译应用程序不需要特定于计算机的设置，因为新人可能会获得新计算机。

如果您即将离开，我强烈建议不要重构您的代码以遵守任何“标准”。良好的风格很重要，但不会引入可能需要由新人修复的新错误。

您的应用程序处于源代码管理状态......对吗？

Answer 9

每个人都认为其他人的代码很糟糕。你应该认为你的代码太糟糕了。为什么？因为它确实如此。确实如此。

我知道当我不得不维护别人的项目并趟过他们的代码时，我发现自己在关于这个人和工作以及负责人的四个字母上喋喋不休......最后，我确实达到了理解并能掌握这个人如何思考问题及其编码风格。

要适应其他人的编码风格并不容易，这就是为什么团队有编码标准和代码审查的原因。这些东西有助于缓解疼痛......至少在大多数情况下都是如此。

如果你已经记录了你的代码和你的项目（即这个东西做了什么？）并且你的程序正在生产中（实际上正在使用！）那么下一个人不应该抱怨太多......除了你的代码：）

Answer 10

这是一篇很有帮助的文章：

http://msdn.microsoft.com/en-us/library/xzf533w0(v=VS.71).aspx

在新人看到你所有bool aintSo = false;语言全部创作之前，你还可以花一点时间来了解你的“Refactor”命令。

Answer 11

学习编写优秀代码的最佳方法之一是阅读优秀的代码，因此您可以尝试下载一些您感兴趣的开源项目，并浏览代码库以查看其他人的操作。 “什么是好的风格”有一百万个答案，明确的共识并不总是容易做到的。

你可以做的绝对最好的事情就是确保你有良好的面对面沟通技巧。根据您自己的特殊舒适度和外向性以及其他相关人员的不同，这可能很容易或很困难。您可以采取一些措施使双方都更容易，但请确保不要陷入仅通过电子邮件进行沟通的陷阱或代码评论是一个很大的问题。如果你有一个关于新人的报告，那么他们会在遇到问题时来找你，而不是为你匆忙创造的代码而烦恼并嘀咕自己。

那就是说，最好的代码是自我记录。必要时使用注释，特别是方法描述或业务逻辑的棘手部分，但尝试确保代码本身在大多数地方都足够可读。这使您可以避免使用太多注释来降低代码可读性。

您问题的具体答案，无需重命名简单的计数器变量，例如i。实际上，在大多数c语言中，i和x通常用于这种情况，因此熟悉这些语言的任何人都会非常舒服。其他变量，特别是类成员变量和方法中使用的变量，确实需要不错的（但不是太长）名称。

Answer 12

通常，最不实用的是变量（例如计数器），名称越短。 '我'是一个标准，所以不要担心。但是，重要的变量以及具有较长使用寿命的变量应具有描述性名称。

如前所述，要保持一致（例如，以小写字母开头，选择使用或不使用下划线......）。

保持你的功能体不到1.5页（主要功能除外），名称也是一致的。

最后，评论黑客，而不是明显的：）

Answer 13

我见过有人使用Index，Indexx，Indexxx等作为计数器。他现在为麦当劳工作。

简而言之：我宁愿看到i，j，k。

Answer 14

我发现ii远远优于我作为我的基本循环计数器。我不记得肯定，但我相信我从Code Complete中学到了这种技巧。为什么它优越？尝试在源代码中搜索i。然后尝试搜索ii。看看哪个更好。

Answer 15

在团队中工作绝对没有替代品，特别是在你职业生涯的早期阶段。

您可以从其他更多经验程序员那里学到的金额非常宝贵。有几种学习模式建议达到最高水平的能力（成为专家），你必须能够与其他专家交谈。与上述几个级别的人建立同伴关系将有助于您比阅读书籍和网站更快地学习。

这里的很多其他答案都很好，并且为学习很多很棒的东西提供了很好的资源，但是我确保你接下来的工作是与你可以学习的真人一起。

Answer 16

约定，评论和文档都很棒，特别是如果你设法解释这些程序的用途以及为什么你以某种方式而不是另一种方式做事。

如果可行的话，我还建议您在离开前花一些面对面的时间向新开发者解释这些项目。这是非常宝贵的。

Answer 17

我会在这里直截了当，但请记住，还有一个平衡点可以找到。

做你付出的工作。对承包商尤其如此。你是否强迫自己的风格在别人身上。遵循公司的编码标准和格式标准。

现在，如果你对公司正在使用的标准有信心，那就错了。你提出并先解释。一旦达成共识，您可以立即使用新标准并获得奖励（点击肩膀），以帮助您保持标准。

如有疑问，请问某人！帮助您与现有团队整合。当你变得更高级时，其他人会来找你。

最后一句话，代码属于支付它而不是开发者的公司，因此请不要像宝宝那样持有它。

Answer 18

对于您用于迭代的变量，通常使用“i”或“x”作为名称。这不会让大多数人感到沮丧 - 如果它确实对某人造成了伤害，那么他们可能还没有看到足够的真实代码才有资格完成你的工作。：）

如果您真的担心某人对您的代码的看法，那么尝试一致地命名内容可能不是一个坏主意。另一方面，不要冒险打破一切只是因为某些人因为让别人喜欢你的变量而感到痴迷，因为无论你做什么，都会有人讨厌他们。如果它有效，并且记录得很好，并且你的变量名称意味着什么（除了上面提到的'i'和'x'变量），那么它就足够“IMO”。

Answer 19

如果您必须将“i”命名为不同的名称，请将其命名为“index”。在您发布的具有尽可能多（缺少）描述的循环中，这是唯一合适的名称。

有时在循环“blah”数组时，将其称为“blahIndex”是合适的。当针对多个数据结构使用多个索引时尤其如此。像“blahIndex”这样的格式会提醒大脑哪个索引与哪个项目一致。

也就是说，编程世界中普遍理解的惯例是称为“i”的变量是索引。这意味着保持“我”不应该让任何人感到困惑。

Answer 20

我曾经历过一段时间，原始代码人员将项目关闭几个星期，因为他不想将他的代码“暴露”给另一个程序员。这就是我记得他的代码。关于他作为一个人。

Answer 21

不，他们没有任何一般标准。

项目（或公司）通常为自己设定编码风格指南。然而，保持一致可能是遵循任何风格指南的规则。

Answer 22

好的，我会在这里成为一个逆向者。

每个人都写下评论不好的代码的原因是，在一天结束时，很少有人进入并捣乱它。

离开公司的真正遗产是运作良好的程序并完成业务人员需要完成的工作。

如何编写代码远不如它是否能完成有用的东西。最容易维护的程序是永远不需要改变的程序，因为它完成了人们想要它做的事情 - 没有大惊小怪，没有麻烦，没有麻烦。

如何让我的代码更容易让下一个开发人员理解？

22 个答案: