ct-2 火箭 运输车

Hello! We are a team at UBC Launch Pad, a club that is devoted to building applications in a collaborative and professional environment. We were tasked with rewriting our internal Slack bot, which is responsible for member onboarding and club team management. These are a few things we tried and a few things we learned along the way while building Rocket 2.

你好！ 我们是UBC Launch Pad的团队，该俱乐部致力于在协作和专业的环境中构建应用程序。 我们的任务是重写内部的Slack机器人，该机器人负责成员入职和俱乐部团队管理。 这些是我们在构建Rocket 2的过程中尝试过的一些事情，也是我们学到的一些事情。

try我们试图降低准入门槛。 (🚧 We try to lower the barrier of entry.)

Our original team knew a plethora of different programming languages, but we eventually decided on Python because of its simplicity and ease of learning. We tried to make running the project as simple as possible, so that developers can start hacking on Rocket as quickly as possible.

我们最初的团队知道很多不同的编程语言，但是由于Python的简单性和易学性，我们最终决定使用Python。 我们试图使项目的运行尽可能简单，以便开发人员可以尽快开始对Rocket进行黑客攻击。

For example, the project utilizes pipenv as the package manager so you can run the project with a simple pipenv run launch (or a docker container, if it tickles your fancy). Similarly, we also tried to simplify Rocket’s configuration system. At first, all configuration options were in environmental variables, which were stored in .env files. Later in development, we switched to TOML files, which proved to be a slight mistake: we ended up with configuration file hierarchies that most of us didn’t completely understand. Few people knew where to put configuration options and simply opted to put them in all of the files just to be safe. It was a classic case of premature optimization — each TOML configuration file only had 2–6 variables. We reverted back to using .env files and further abstracted the configuration options. You no longer have to read the code to know about the configuration hierarchy, and instead just put your variables in a .env file. Each developer now knows immediately if they have included all of the necessary environmental options — the program will let you know the specific ones you have forgotten to include.

例如，该项目利用pipenv作为程序包管理器，因此您可以使用简单的pipenv运行启动 (或者，如果您喜欢，可以使用docker容器)运行该项目。 同样，我们也尝试简化Rocket的配置系统。 首先，所有配置选项都位于环境变量中，这些环境变量存储在.env文件中。 在开发的后期，我们切换到TOML文件，事实证明这是一个小错误：我们最终遇到了我们大多数人都不完全了解的配置文件层次结构。 很少有人知道在何处放置配置选项，只是为了安全起见只是选择将它们放在所有文件中。 这是过早优化的经典案例-每个TOML配置文件只有2–6个变量。 我们恢复使用.env文件，并进一步抽象了配置选项。 您不再需要阅读代码来了解配置层次结构，而只需将变量放入.env文件中。 现在，每个开发人员都会立即知道他们是否已包括所有必需的环境选项-该程序将使您知道忘记包括的特定选项。

🤖像往常一样，强调自动化。 (🤖 Like always, there is an emphasis on automation.)

We talked about automating code linting and test suites. As a result, we run our code through a series of code linters. We require that every pull request follow the PEP8 style guide, have documented classes/functions everywhere, and have well-written markdown. Our documentation is built automatically per deployment, so there aren’t any frustrations with out-of-date documentation.

我们讨论了自动化代码整理和测试套件。 结果，我们通过一系列代码套子运行我们的代码。 我们要求每个拉取请求都遵循PEP8样式指南，到处都有记录的类/函数，并具有精心编写的markdown。 我们的文档是根据部署自动生成的，因此对于过时的文档不会有任何挫败感。

To avoid non-trivial typing issues sometimes caused by unruly asserts, we utilize the static type checker mypy to check for mismatched types (e.g. a string as parameter to a function that only accepts integers). This prevents team members from submitting code that assumes the type of a parameter, which has historically caused everything to crash.

为了避免有时由不合理的 断言引起的非平凡的键入问题 ，我们利用静态类型检查器mypy来检查类型不匹配的类型(例如，字符串作为仅接受整数的函数的参数)。 这样可以防止团队成员提交采用参数类型的代码，而该代码在历史上一直导致崩溃。

📚不仅鼓励记录，还必须这样做。 (📚 Documentation is not only encouraged, it is mandatory.)

For team members who weren’t completely sure how some aspect of this project worked, we encouraged them to write about it to help them learn. This resulted in a lot of documentation about the different moving parts in this project which you can read on our documentation site here. It contains both information for developers (how to build and run the project, API references, etc.) and end users (how to use the different Slack commands).

对于不完全确定该项目某些方面如何工作的团​​队成员，我们鼓励他们写这篇文章以帮助他们学习。 这产生了大量有关该项目中不同运动部件的文档，您可以在此处的文档站点上阅读这些文档。 它既包含针对开发人员的信息(如何构建和运行项目，API引用等)，也包含针对最终用户的信息(如何使用不同的Slack命令)。

This rigorous emphasis on documentation helped the project survive 4 semesters of 3 largely different teams of people. By having more eyes on the documentation, it was able to gradually improve — Each generation of developers is able to learn from past contributors.

对文档的严格重视帮助该项目在3个不同团队的4个学期中得以幸存。 通过更多地关注文档，它可以逐步进行改进—每代开发人员都可以向过去的贡献者学习。

always重构和提高代码质量始终在我们的脑海中。 (✨ Refactoring and improving code quality is always on our minds.)

We have been actively working on this project for around 2 academic years, and team members often suggest improvements to the code. We try to make sure that all the code is verbose and reasonably abstracted.

我们已经为这个项目积极开展了大约2个学年的工作，团队成员经常建议对代码进行改进。 我们试图确保所有代码都是冗长且合理的抽象。

It recently came to our attention that some of our documentation was not very useful; it was only put into the code because of our strict (former) linting standards. The docstrings required at the top of every file were mostly useless and just padded out the line count. The same was said for the docstrings at the start of test suite setup functions, trivially short constructors, and verbose functions. In response to our observations, we removed the requirement. Of course, the culture of adding well-documented classes and functions has not left the project entirely — over 90% of the project still has documentation. The rule has simply transformed from a hard, do-this-or-your-build-fails rule into a soft, do-this-or-your-PR-gets-rejected rule.

最近引起我们注意的是，我们的某些文档不是很有用。 只是因为我们严格的(以前的)棉绒标准，才将其放入代码中。 每个文件顶部所需的文档字符串几乎没有用，只是填充了行数。 在测试套件设置函数，琐碎的构造函数和冗长的函数开始时，对于文档字符串也是如此。 根据我们的观察， 我们删除了要求 。 当然，添加有据可查的类和函数的文化并没有完全摆脱该项目-超过90％的项目仍具有文档。 该规则已从硬性的，执行此或您的构建失败的规则简单地转变为软性的，执行此或您的PR获取拒绝的规则。

When we initially designed Rocket 2, we wanted to use Python’s built-in argparse library to parse the slack slash commands as you would parse standard command-line commands. Unfortunately, we found that argparse wasn’t built for this: Whenever a user inputs an invalid command-line command, argparse wouldn’t just complain. It would take out the entire program by raising a SystemExit exception, which effectively shuts down the server. The solution we came up with was this: to catch the SystemExit exception and display help text — crude, yet effective. Plans to switch to a different library are already underway.

最初设计Rocket 2时，我们希望使用Python的内置argparse库来解析松弛的斜杠命令，就像解析标准命令行命令一样。 不幸的是，我们发现argparse不是为此而构建的：每当用户输入无效的命令行命令时， argparse都不会抱怨。 它会通过引发SystemExit异常来删除整个程序，从而有效地关闭服务器。 我们想到的解决方案是：捕获SystemExit异常并显示帮助文本-粗略而有效。 切换到其他库的计划已经在进行中。

try: args = self.parser.parse_args(command_arg)except SystemExit: all_subcommands = list(self.subparser.choices.keys()) present_subcommands = [subcommand for subcommand in all_subcommands if subcommand in command_arg] present_subcommand = None if len(present_subcommands) == 1: present_subcommand = present_subcommands[0] return self.get_help(subcommand=present_subcommand), 200

未来与未来 (The future and beyond)

Rocket 2 is currently in maintenance mode (what I’d call “passive development”). In the past, we have had 3 separate teams working on it. Most of the core features and functionalities are already implemented. However, we still have a number of things in store, mostly things that help with the upkeep of the project, such as refactors and clean-ups. There is still a lot of room for improvement.

火箭2目前处于维护模式(我称之为“被动开发”)。 过去，我们有3个独立的团队来进行这项工作。 大多数核心功能已经实现。 但是，我们还有很多东西要保存，大部分是有助于项目维护的东西，例如重构和清理。 仍有很大的改进空间。

Check out the Rocket 2 repository if you want to have a look. And if you see something amiss, feel free to make an issue or pull request!

如果要查看，请查看Rocket 2信息库 。 如果发现不对劲，请随时提出问题或提出要求！

ubclaunchpad.comubclaunchpad.com — UBC’s leading software engineering club. — UBC领先的软件工程俱乐部。 Stay in touch: 保持联系： FacebookFacebook | | InstagramInstagram | | LinkedInLinkedIn | | Newsletter通讯

翻译自: https://medium.com/ubc-launch-pad-software-engineering-blog/rocket-2-and-the-importance-of-good-software-development-practices-documentation-and-testing-fe6b7236fce0

ct-2 火箭 运输车