体面编码之文件 格式化和依赖管理

18-12-31 banq
              

根据惯例对文件实现良好命名。请参阅命名事项。遵循项目约定(例如后缀)和套管样式。

在适当的文件夹中。考虑因素包括目的和功能区域。

由功能分离组织,而不是按文件类型。这意味着应用功能区/模块或组件 - 而不是文件类型(例如控制器,样式,DAO)。以这种方式构建将相关代码保持在一起,这有助于发现和导航。

测试文件接近他们正在测试的代码。单独src和test文件夹的标准Java约定与此相反。将它们放在附近会使它们更容易找到,让它们留在人们的脑海中,并且很容易发现它们。实际上,这意味着将它们放在兄弟文件夹中,放在他们正在测试的文件中。

格式化

几乎所有的格式问题都应该通过ESLint或Checkstyle等工具实现自动化。违规行为应该使构建失败,以免它们积累并使新的构建难以注意到。

本地开发(文件监视)构建不需要在违规时失败,以免它成为令人烦恼的不便。应签入并共享符合要求的编辑器/ IDE设置,例如使用EditorConfig文件。还要考虑使用源代码控制预提交挂钩运行自动检查。

以下仅包括正确的关键事项; 它不是一套全面的自动化工具设置。

使用一致的行结尾。源控制工具认为具有不同结束中断的其他相同线条是不同的。在项目中混合将导致不必要的差异噪声(使代码更难以查看)和合并问题,尤其是在重构期间移动代码时。

使用一致的缩进。“虚假差异”的另一个原因。混合风格将导致上述问题。

避免留下尾随空格。它们是“虚假差异”的根源,没有充分理由拥有它们。

使用换行符结束文件。这样可以避免在以后添加新行时将现有的最终行视为diff中的修改。

明智地使用单个空行来分隔构造和语句组。空行在逻辑部分之间创建视觉分离,使代码更易于阅读。密集代码更难阅读。示例包括在一组变量声明之后,围绕if-else语句,在方法的逻辑部分周围,以及在return语句之前。

避免对格式化,缩进等进行任何不必要或不相关的更改。它们会降低手头工作的目的,导致差异噪声(以及上述相关问题),并使逐行更改历史记录变得不那么有用。此问题通常出现在不遵守(或强制执行)这些准则的代码库中,尤其是在打开编辑器/ IDE自动格式功能时。

如有疑问,请查看现有代码。项目中的现有代码将说明既定的惯例。

避免个人商标。通过阅读代码来告诉谁写它是不可能的。就格式而言,如果使用适当的规则设置自动化工具,这不应成为问题。

依赖

考虑是否真的需要使用库/工具。如果可以使用几行简单的代码完成手头的任务,则可能不值得添加新的依赖项。熟悉最新的平台/ SDK和已经存在的库 - 您需要的可能已经可用。

仔细选择库/工具。考虑包括质量,受欢迎程度,文档,“活力”,弃用和社区力量等因素。审查备选方案 根据库的性质,它的使用可能位于项目的某个区域 - 或者广泛使用并与应用程序代码交织在一起。后者需要特别小心。

内部公司库包/工具/框架如果没有获得免费通行证。这些问题与开源问题一样容易受到影响(可能更是如此)。例如,它们可能质量差,没有文件记录或被遗弃。内部图书馆很少有社区,并且不受像开放源代码那样的消费者选择。

确保许可证与我们的使用兼容。某些许可证与典型的商业用途不兼容。在选择许可的网站拥有最流行的许可证的便利摘要。

通常使用最新的非beta版本。这些应该是稳定的,包括最新的功能和错误修复,可能会收到错误修复,并有易于访问的文档。与其他人密切互动或拥有插件生态系统的新发布的主要版本的依赖项可能值得推迟,直到周围的景观赶上并安定下来。

检查库是否不会破坏您构建的脚手架。如果您的应用程序通过互联网 - 在网络上或作为移动应用程序提供给用户,则适用。使用生态系统中的工具来分析构建的自己脚手架。

遵循已建立的模式和习惯用于给定的依赖关系。主要的图书馆,框架和工具通常都有一种有效使用它们的既定方法。这可能是官方和社区驱动的结合。熟悉它将帮助您充分利用它们并避免反模式。阅读不仅仅是入门页面。

由于无知,避免重新实现库/框架功能。尝试熟悉已有的“标题功能”。无法了解所有内容并保持最新状态,因此您可以找到以下经验法则,以便快速考虑是否已经可以使用某些内容:1)我是否可能是第一个使用库-X需要此功能的人?2)如果我正在编写自己的库-X,我会包含此功能吗?