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

Question

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

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

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

例如,我总是做这种事情.

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

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

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

是否有任何资源可以告诉我如何让下一个开发人员更容易？这种类型的东西有标准吗？

Answer 1

史蒂夫麦康奈尔的代码完整是一个很好的地方,开始寻找你的问题的答案,还有很多你尚未提出但很快就会提出.

Answer 2

如果您已经完成以下任务,那么缓解替代者的痛苦将会有很长的路要走:

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

如果你想要遵守编码标准,那么SO上有一个相关的帖子,它有一些建议.

Answer 3

除了"实际工作"(以前的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

我可以从经验中告诉你:其他人不会写出漂亮的代码.真的,如果您的代码以某种方式记录,它已经比平均值好很多.

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