开发者必学：用英语写清晰的 README 和 PR

很多开发者第一次在 GitHub 上贡献代码时，都会遇到同样的困扰：明明代码写得没问题，但是用英语写 README、提 Issue 或者发 PR 的时候，总觉得表达不够准确，担心别人看不懂自己想说什么。

这种担心其实很正常。技术英语和日常英语确实不太一样，它有自己的表达习惯和常用句式。好消息是，掌握了一些基本套路之后，你会发现写这些文档其实比想象中容易很多。

README：让别人快速理解你的项目

README 是别人了解你项目的第一扇窗户。一个清晰的 README 通常会按照这样的顺序来组织信息：先说这个项目是做什么的，然后告诉别人怎么用，最后提供一些额外的帮助信息。

项目介绍部分最好开门见山。比如说"This project helps you manage your daily tasks more efficiently"就比"This is an awesome task management tool"要好。前者直接说明了项目的作用，后者只是在夸自己。

接下来的安装和使用说明是最关键的部分。这里要站在完全不了解你项目的人的角度来写。每一步操作都要清楚明确，不要跳过任何看似"显而易见"的步骤。比如安装依赖，你可以写"Install dependencies by running npm install"，而不是简单地写"Install dependencies"。

代码示例也很重要。一个好的示例应该是完整可运行的，不需要读者去猜测缺失的部分。比如你在展示一个 API 调用时，最好把导入语句、初始化代码和实际调用都写完整。

Issue：准确描述问题和需求

写 Issue 的时候，最重要的是让维护者能够快速理解你遇到的问题或者你想要的功能。很多开发者会犯一个错误，就是描述问题时过于简略，比如只写"It doesn't work"。这样的描述对解决问题没有任何帮助。

报告 Bug 时，要按照"现象-期望-环境"的顺序来组织信息。先描述你看到了什么异常现象，然后说明你期望看到什么结果，最后提供你的运行环境信息。比如："When I click the submit button, the page shows a 500 error. I expected the form to be submitted successfully. I'm using Chrome 91 on macOS 12.1."

如果可能的话，提供能够复现问题的最小示例。这不仅能帮助维护者更快地定位问题，也证明了你确实花时间调查过这个问题。

请求新功能时，要说明为什么需要这个功能，而不是只说想要什么。比如："I often need to batch delete multiple items, but currently I have to delete them one by one, which is time-consuming"就比"Please add batch delete feature"要好得多。

PR：清晰地说明你的改动

Pull Request 是你向项目贡献代码的正式途径，所以描述要更加仔细。一个好的 PR 描述应该让审查者明白三件事：你改了什么，为什么要改，以及这个改动是否安全。

标题要简洁但信息完整。"Fix user login bug"比"Bug fix"要好，"Add email validation to user registration"比"Update user.js"要好。标题应该能让人一眼看出这个 PR 的主要目的。

在描述正文中，先解释背景。什么问题促使你做这个改动？如果是修复 Bug，简单描述一下 Bug 的表现；如果是新功能，说明一下使用场景。然后详细说明你的解决方案，特别是如果你考虑过多种方案的话，可以简单提及为什么选择了当前这种。

测试信息也很重要。告诉审查者你是如何验证这个改动的。比如："I tested this change by creating a new user with an invalid email address, and confirmed that the validation error is properly displayed."

让你的英语更地道

在实际写作过程中，有一些小技巧可以让你的英语表达更自然。

首先是时态的使用。描述现状用一般现在时，比如"This function returns the user's email"；描述你做的改动用过去时，比如"I added validation for the email field"；描述预期效果用将来时或情态动词，比如"This change will prevent invalid emails"或"Users should no longer see the error message"。

其次是语气的把握。在 GitHub 这样的开源环境中，礼貌但直接的语气最合适。你不需要过度客气（比如"I'm sorry to bother you, but..."），但也不要过于生硬。"Could you help me understand why..." 比 "I don't understand why..." 要好一些。

最后是一些常用的表达方式。比如描述问题时可以用"I'm experiencing an issue where..."，请求帮助时可以用"I would appreciate any guidance on..."，说明改动时可以用"This PR addresses the issue by..."。

这些表达方式你用多了就会成为习惯，慢慢地你会发现自己不再需要刻意去想该怎么表达，自然就能写出清晰准确的技术文档了。最重要的不是英语有多完美，而是能让别人理解你想表达的意思。