Question

我们都知道，编写好的代码很重要，重构迫使我们考虑让方法变得更小、更可复用和自文档化。有人说注释是有害的，自注释的代码才应该是我们的追求。不管你怎么做，我们每个人都应该追求易于阅读、理解和维护的好代码。但是代码不会讲述完整的故事。

让我们想象一下，你新加入一个正在进行中的软件项目。主要的结构单元都到位了，已经交付了一些功能。你启动了自己的开发机，从源代码控制系统下载了代码并加载到你的开发环境中。下一步要做什么，如何变得有效率？

从哪开始

如果没人有时间带你过一遍代码库，你可以根据对这个项目有限的了解、业务领域、你对团队如何构建软件的期望以及你对所用技术的知识，做出自己的假设。

举个例子，你可以通过代码库如何被拆分为子项目、目录、包、命名空间等对软件系统的整体架构做出一些判断。说不定有一些正在使用的命名约定。我们甚至能够从前面的微软Visual Studio屏幕截图判断出软件的一些特征，在这种情况下它是一个（匿名）的网上银行系统。

系统用C#在微软.NET平台上编写。

整个.NET解决方案被分拆为很多个Visual Studio项目，有一个被称为ib.web的.NET Web应用程序，你已经料到了，因为这是一个网上银行系统（IB即“网上银行”）。

系统似乎是由多个架构层组成的。有ib.web和ib.middletier，但我不知道是否有物理或逻辑层。

项目看起来有一个命名约定。如，iib.middletier.authentication.lib 、ib.middletier.messaging.lib和b.middletier.bankingsystem.lib似乎都是中间层相关的类库。这些仅仅是类的一种逻辑分组，还是一些更重要的东西，比如高层次组件和服务？

借助一些技术知识，我能够看到ib.web项目下潜藏了一个“服务引用”文件夹。这是Windows通信基础（WCF）服务的引用，在这个例子中，基本上就是Web服务的客户端。它们的命名似乎对应了中间层的类库，因此我认为我们实际上拥有的是一个分布式系统，它有一个暴露了一些良好定义的服务的中间层。

代码未描绘的设计意图

进一步深入代码会帮助验证你最初的假设正确与否，但也可能留给你一大堆问题。也许你在较高层次明白系统做的事情，但不明白像下面这样的事。

软件系统如何融入已有的系统形态；

为什么会选择正在使用的技术；

软件系统的整体结构；

各个组件在运行时部署在哪里，如何相互沟通；

Web层如何“知道”在哪里找到中间层；

日志/配置/错误的处理/其他采用了什么方法，在代码库中是否一致；

代码库中是否使用了通用的模式和原则；

如何添加新功能，在哪里添加；

栈的安全性是如何实现的；

如何实现可伸缩性；

与其他系统的接口如何工作；

其他。

我曾被要求评审和参与开发没有文档的系统。你当然可以从代码的角度评估大部分问题的答案，但这会很繁重。阅读代码的作用始终有限，但某些时候你可能需要向团队的其他人请教一些问题。如果没有问对问题，你就得不到正确的答案：你不知道你未知的。

辅助信息

任何软件系统，在代码之上都有另一个可以回答这些类型以及更多问题的信息层。

代码之上还有一个额外的信息层

这类信息和代码是互补的，应该在某处被捕获，比如轻量级的辅助文档，它能描述代码自己无法描述的东西。代码会讲故事，但不会讲述完整的故事。