如何让我的代码更易于下一位开发人员理解?

我已经进行了大约8个月的第一次编程工作,到目前为止我已经学到了不可思议的数字。

不幸的是,我是内部应用程序的小创业公司的唯一开发者。

有史以来第一次,当我离开这个工作时,我会把我的一些项目交给别人。 我已经完整地logging了我的所有项目(至less我是这么认为的),但是对于别人阅读我的代码,我仍然感到紧张。

例如,我一直都是这样做的。

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

我应该说“我”是描述性的吗? 这只是一个临时variables,并且只会存在于这个循环中,似乎很明显,循环对'i'做了什么。

这只是一个例子。 另一个是我的variables名称不同…除了开始所有私人成员的下划线之外,我没有真正遵守一个命名标准。

有没有什么资源可以告诉我如何让下一个开发者更容易? 这种types的东西有标准吗?

由史蒂夫·麦康奈尔代码完成是一个好地方开始寻找你的问题的答案,还有更多的你还没有问,但很快就会。

如果你已经完成了以下工作,将会大大减轻替代者的痛苦:

  1. 生成一个架构文档,显示您的软件的整体结构以及哪些部分进行交互。
  2. logging每个成员variables/函数/类来表明他们做什么(而不是如何做)。
  3. 编写和logging一些testing,这些testing显示了你的程序是如何运行的,以及你希望以什么样的方式使用它。 确保logging任何示例数据,以便您的replace可以重新运行testing,以了解应该如何工作。
  4. 确保你的代码遵循一个标准。 即使不是传统的代码,至less与自身一致的代码也会更容易遵循。
  5. 如果您对此感到满意,请留下一些联系方式,以便那些接class的人或者至less可以通过电子邮件发送电子邮件或给他们打电话。 我已经为各种项目/工作做了这个。 回答这个奇怪的问题并不需要很长时间,但是可以很容易地节省那些inheritance了代码库的倾注灵魂。

如果你想要遵守一个编码标准,这里有一个相关的post,这里有一些build议。

请记住,我们(程序员)是一群傲慢的(也是很无知的)一群怪人,除了“实际工作”(前面的3个答案是相当不错的)

不pipe你如何努力编写好的(和有文档的)代码,或者你应用了多less语法糖:对于新人来说,你的代码总是会“吸”(至less在某种程度上),因为没有写它。

对于你的例子(使用我为循环),它只是一个本地循环variables。 我对你自己不会太难 只要代码几乎是自我解释,他只需要pipe理。

其中variablesi被认为是一个特殊的命名案例。 与jkli被很好地理解为在循环中使用的临时“计数器”variables。 只要你的使用是一致的,这不会是一个问题。

这里有一些很好的规则可以让你的代码更容易理解:

  • 保持一致 :确保您的variables命名约定和devise是一致的。 如果你经常为循环创build临时variables,他们总是被称为i吗? 你在其他地方用i意思是不同的? 一致性意味着你的代码有一些逻辑模式。 模式很容易接受和遵循。
  • 解释自己 :确保评论解释你为什么做某事,而不是你在做什么。 像/ / // Loop over array评论不帮助; 任何人都可以阅读你的代码,并看到你正在执行一个循环。 他们想知道的是为什么你这样做。
  • logging你的类 :给每个类,接口,成员,属性的目的文件,即使它只是一个单行的解释,当试图理解一个应用程序的组件时,是一个巨大的帮助。 如果在Visual Studio中打开XML注释,则每次忘记添加每个成员的最小摘要时,都会生成警告。 这些评论还有智能感知支持的额外奖励,使您的代码更容易处理。

如果你可以说你的代码遵循这些准则,我会很高兴inheritance你的代码。 坦率地说,我还没有给出一个代码库,甚至跟着这些build议之一,但我写我自己的代码,试图让下一个工作更容易。

有两个工具,我知道可以帮助你很多。 StyleCop和FxCop 。 按照链接了解这些工具是什么。 拥有这些工具的一大优势是,您不必手动完成代码,这无疑需要很长时间。

我可以从经验告诉你: 别人不写漂亮的代码 。 真的,如果你的代码被logging下来了,那么平均值已经比较好了。

别紧张。 有数百种方法来写相同的。 每个开发者都认为他的方式是最好的。 恕我直言,关于编码风格的唯一事情是一致性。 所以如果你“总是做这样的事情”,你有一致的代码。

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

至于另一个例子,这是主观的,只要你在惯例中一致,你应该没问题。

主要是:一致

编辑:至于参考,这里是你可以使用的一个:

代码名称约定参考

这应该是显而易见的,但要确保每个生产组件都有源代码随时可用,并处于可编译状态。 确保没有机器特定的设置来编译您的应用程序,因为新的人可能会得到一台新的机器。

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

而你的应用程序在源代码控制…对吗?

每个人都认为别人的代码很糟糕。 而且你应该认为你的代码太糟糕了。 为什么? 因为它。 它确实如此。

我知道,当我不得不维护某个人的项目并通过他们的代码进行沟通时,我发现自己嘟four了四个字母关于这个人,这个工作和负责人的话……最后,我确实达到了理解的程度了解这个人如何思考问题和他们的编码风格。

要适应其他人的编码风格并不容易,这就是团队编码标准和代码评审的原因。 这些东西有助于缓解疼痛……至less在大多数情况下。

如果你已经logging了你的代码和你的项目(即这个东西是做什么的?),你的程序正在生产(实际上正在使用!),那么下一个人应该没有太多抱怨…除了你的代码:)

这是一个很好的文章,可以帮助你:

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

你也可以花一点时间在新人看到你所有的bool aintSo = false;之前知道你的“ Refactor ”命令bool aintSo = false; 语言遍布创作。

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

你可以做的绝对最好的事情,让来自程序员更容易的事情是确保你有良好的面对面的沟通技巧。 这可能很容易或难以取决于你自己的特殊的舒适性和外向性,也可能是其他人。 有一些事情可以使你们更容易,不要掉进通过电子邮件或代码评论的沟通陷阱。 如果你有新来者的报告,他们会在有问题的时候find你,而不是对你自己创build的代码感到困惑。

这就是说,最好的代码是自我logging。 必要时使用注释,尤其是方法描述或业务逻辑的棘手问题,但要尽可能确保代码本身在大部分地方都具有足够的可读性。 这使您可以避免通过太多的注释来减less代码的可读性。

你的问题的具体答案,没有必要重新命名简单的计数器variables,如我。 事实上,在大多数c语言中,我和x通常用于这种情况,所以熟悉这些语言的任何人都会很自在。 其他variables,特别是类成员variables和方法中使用的variables,确实需要体面的名称(尽pipe不会太长)。

通常,最没有用的是一个variables(例如计数器),名字越短。 '我'是相当标准的,所以不要担心。 然而,重要的variables,以及具有长寿命的variables应该有一个描述性的名称。

正如前面所说的那样,要保持一致(例如,所有的variables都以小写字母开头,select使用或不使用下划线…)。

保持你的函数体less于一个半页(主函数除外),也有描述性和一致的名字。

最后,评论黑客,而不是显而易见的:)

在团队中工作是绝对不能替代的,特别是在职业生涯的早期阶段。

你可以从其他更多的经验程序员学习的数量是非常宝贵的。 有几种学习模式build议达到最高水平的能力(成为专家),你必须能够与其他专家交谈。 与以上几个层次的同伴关系将帮助你学习远远超过阅读书籍和网站的速度。

很多其他的答案都很好,并且提供了很多很好的资源来学习,但是我会确保你的下一份工作是与真实的人们一起学习。

我发现ii比我的基本循环计数器要优越得多。 我不太确定,但我相信我从“代码完成”中学到了这一技巧。 为什么优越? 尝试在您的来源中search我。 然后尝试searchii。 看看哪个更好。

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

简而言之:我宁愿看到我,j,k。

没有他们没有任何一般的标准。

项目(或公司)通常为自己设置编码风格指南。 然而,一致可能是遵循任何风格指南的规则。

对于用于迭代的variables,通常使用“i”或“x”作为名称。 这不会影响大多数人 – 如果确实有人在做错事,那么他们可能没有看到足够的真实代码来胜任工作。 🙂

如果你真的担心别人对你的代码有什么看法,那么试图一直命名的东西可能不是一个坏主意。 另一方面,不要去冒险破坏一切,只是为了让其他人像你的variables名一样痴迷,不pipe你做什么,都会导致别人恨他们。 如果它能正常工作,而且它的logging很好,而且你的variables名称意味着某些东西(除了上面提到的'i'和'x'variables),那么IMO就足够好了。

公约,意见和文件是伟大的,特别是如果你能够解释什么是程序的目的,为什么你以一种方式而不是另一种方式做事。

如果可行的话,我也build议在离开之前花一些面对面的时间向新开发者解释项目。 这是无价的

我会在这里钝的,但请记住,也有一个平衡被发现。

做你所付出的事情。 对承包商尤其如此。 你强迫别人的风格吗? 遵循公司的编码标准和格式标准。

现在,如果你确信公司正在使用的标准,是不是有什么错误。 你首先提出并解释。 一旦达成共识,你可以立即使用新的标准,并获得一个奖励(肩上),你有助于保持标准。

如有疑问,请问一个人! 帮助你整合现有的团队。 当你变得更高级的时候,别人会来找你。

最后一句话,代码属于付费的公司,而不是开发商,所以不要把它当作宝贝。

如果你必须把“我”的名字命名为“索引”。 在一个循环中,尽可能多的(缺less)描述,这是唯一适用的名称。

有时在循环“blah”数组时,可以将其称为“blahIndex”。 当对多个数据结构使用多个索引时尤其如此。 像“blahIndex”这样的格式将提醒哪个索引与哪个项目相关联。

也就是说,在编程世界中这是一个通常被理解的约定,称为“i”的variables是索引。 这意味着保持“我”是不应该混淆任何人。

我经历过一段时间,原来的代码人把这个项目放了几个星期,因为他不想把代码暴露给另一个编码器。 这就是我记得他的代码。 关于他作为一个人。

好吧,我会在这里成为一个逆向的人。

每个人写出评价很差的代码的原因是,在这一天结束的时候,很less有人会进入这个代码。

离开你公司的真正遗产是能够很好地运作的项目,并且能够满足业务人员的需求。

如何编写代码比它是否完成一些有用的东西重要得多。 要维护的最简单的程序就是永远不需要改变的程序,因为它符合人们的需求 – 没有大惊小怪,没有麻烦,也没有麻烦。