写作方法2017alexkras.com编辑精选
写出好代码很像写好散文
Writing Good Code Is a Lot Like Writing Prose
导读
这篇文章把写好代码比作写散文，强调写作前先明确意图、先理解已有内容，并通过结构和衔接让读者顺畅理解。对写作者来说，它提醒我们：清晰表达、逻辑过渡和可读性并不是代码独有的问题，而是所有写作的共同基本功。
可以直接用的写作要点
- 01
动笔前先写一段“意图说明”：我想让这段内容/这段代码做什么。
- 02
先读懂已有材料再开始写，避免一上来就凭表达欲动手。
- 03
用清晰的过渡和连接词把看似分散的想法串起来，别让读者面对孤立的片段。
- 04
把命名、结构和注释当成“文法”，优先让读者读得懂，而不是只让自己写得爽。
HN 评论精选
开发者常低估散文写作，先写意图说明、给出模板能降低写作门槛。
这篇文章很有意思。在我看来，无论写代码还是写散文，带着明确意图进行结构化写作，在各水平开发者中都很罕见。我给新人的关键建议之一是：先写一段说明你的意图——你想让这段代码做什么。这对很多人并不直观，因为它要求先理解现有内容，再动手写代码。根源可能是你拿钱就是来写代码的，想一开始就证明自己。因此，几年前我负责一个工程师招聘站点时觉得很有意思：核心是一系列展示近期工作的博客文章，我很快成了主编，和不同级别的工程师合作，弄清他们做了什么、哪里酷，再让他们写出来。我们定了七篇文章，我安排七天后读初稿，结果七天后没有初稿。深入后发现，他们都以为自己能像写代码一样直接写散文，但都说写散文其实很难。我提供了自己历年文章的模板，到下一季度完成了三篇。
dayjah查看英文原文
This is an interesting read. The structured approach to writing (code or prose) with intent is surprisingly rare among developers of various skill levels in my experience. One of the key pieces of advice I give to new recruits is "write a paragraph about your intent, what do you want this code to do?". This, it turns out, is non-intuitive for folks as it requires first understanding what is there (OP notes this well) before jumping into coding. I think the root of this is that you're paid to write code and you want to impress right from the start. Thus I found it very interesting when a few Q4's ago I was tasked with creating a new recruiting site for engineers ( https://engineering.twitch.tv ) to better understand our culture. The central focus of this site was to be a series of blog posts which highlighted core work that had recently taken place. My job quickly became editor in chief; working with engineers of various levels to understand what they've been doing, what was cool about it, and get them writing about it. Seven blog posts were identified and I made calendar events to check in seven days from then to read drafts... seven days later no drafts existed. As I dug into this it was apparent that they'd all assumed they could jump into the writing prose much like they do code, they all remarked that writing prose is actually really hard. I provided a template of my own pieces over the years and by the following quarter we had three pieces written! I credit TPW for giving me words to describe this to engineers ( http://tom.preston-werner.com/2010/08/23/readme-driven-development.html ) and my high school English teachers for giving me the love of words!
把读代码当成读文学作品，靠重读、讨论、做笔记和查词来建立理解。
更有用的一面是：理解一个代码库或库的过程，在某些方面很像理解一部文学作品。它需要时间，需要重读一点，和同样在读的人讨论，在页边做适量的笔记，遇到不懂的术语查词典。如果是不懂的语言，可以慢慢翻译，但懂基础会大有帮助。我喜欢这个视角，因为它更关乎获得理解，而不是推广某种关于文档的语义风格。
newman8r查看英文原文
I think the more useful side to this is that the path to understanding a codebase or library is in some ways like understanding a literary work. It takes some time, rereading a bit. discussing it with other people who are reading it, making the right amount of notes in the margin, consulting the dictionary when you don't understand a term. If it's in a language you don't know, you can translate it slowly, but knowing the basics goes a long way. I like this way of looking at it because it has more to do with gaining understanding than with promoting some semantic style in regards to documenting
好写作靠逻辑过渡连接思想，代码也应通过注释和自文档化建立连接。
我在大学的一个混合项目里同时学英语和计算机科学。吸引我的一点是，写好代码和写好文章是平行的。写作，尤其是写论文或长文，依赖逻辑：必须要有清晰的桥梁或过渡，把有时看似不相干的想法连接起来。我写代码时也试图用同样的原则。我不想让人看到两段孤立的代码就想：“搞什么，这些东西甚至不属于同一个宇宙，更别说同一个仓库了。”无论是通过注释，还是靠好的自文档化代码，我都希望东西能连接起来。Jeremy Ashkenas 在关于 CoffeeScript 的文章里也做过类似联系，那对我算是一个顿悟时刻。
altotrees查看英文原文
I studied both English and CS in a hybrid program in college. One of the things that appealed to me about writing great code is that it did parallel good writing. The process of writing, especially a paper or a longer thesis relies on logic. There have to be clear bridges, or segues between sometimes disparate thoughts, connecting them. I find when I am writing code, I try to use the same principles. I don't want anyone to look at two isolated pieces of code and think "what the hell, these don't even belong in the same universe, let alone the in same repo." Whether through comments or just good self-documenting code, I want things to connect in some way. Jeremy Ashkenas made the connection in a piece of his writing about coffeescript as well. Kind of an ah-ha moment for me.
认同观点，但缺少代码示例，应展示实例来证明。
我同意应该努力让好代码对人类可读，我也经常尝试以语法正确的方式使用命名，让阅读更容易。不过这篇文章让我希望他能展示所谈论的例子。我想看他的代码，判断它是否真的更像散文。
jcbrand查看英文原文
I agree that one should strive to make good code human-readable and I often also try to use names in a grammatically correct way (to make reading easier). However, this article leaves me wishing he'd show examples of what he's talking about. I'd like to see his code to determine whether it reads more prose-like.
同类还值得读
被低估的工程技能：把文章写好
Undervalued Engineering Skills: Writing Well
这篇文章讨论为什么“写得好”是被低估的工程能力，以及它如何在团队协作、系统设计和职业发展中持续带来回报。
写作方法2019 · 1,109 分 · 371 评4 条写作要点编辑精选每行只写一句话：让写作和修改都更轻松的排版法
Writing one sentence per line
这是 Derek Sivers 的一篇短文，主张写作时每行只放一个句子，而不是按段落排版。
写作方法2022 · 849 分 · 297 评4 条写作要点编辑精选书面沟通是远程工作的超级能力
Written communication is remote work super power
这篇文章讨论远程工作中书面沟通的价值，评论区则补充了异步与同步沟通的适用场景，并提醒读者：备忘录、结论先行、结构化命令格式等书面沟通传统早已有之。
写作方法2020 · 831 分 · 190 评4 条写作要点编辑精选如何写出有用的文字
How to Write Usefully
保罗·格雷厄姆在这篇文章里给"有用的写作"下了一个可操作的公式：有用≈重要×新颖×正确×清楚，任一项为零，整篇文章就等于零；他还主张敢下确定判断、删掉让自己心虚的句子。
写作方法2020 · 821 分 · 285 评4 条写作要点编辑精选如何写得更清楚、想得更清楚，并学会复杂材料（PDF）
How to write more clearly, think more clearly, and learn complex material [pdf]
这份 PDF 讨论如何把文章写清楚、把思路理清楚，并用写作来学习复杂材料。
写作方法2022 · 779 分 · 153 评4 条写作要点编辑精选