程序员的技术写作-HTML、CSS、JavaScript、Python、PHP、C++、Dart
文章目录
程序员的技术写作-HTML、CSS、JavaScript、Python、PHP、C++、Dart
HTML、CSS、JavaScript、Python、PHP、C++、Dart--有这么多的编程言语,你以至可能完整通晓其中的几种。但是,随着我们的目的是写出更多、更好的代码,我们用日常言语写作和交流的方式变得越来越重要......以至可能被疏忽了。
我们编写和讨论代码的方式能够说与代码自身同样重要。虽然你可能在这个问题上持不同观念,但我们都能够同意,我们的言辞既会进步代码的有效性,也会损伤代码的有效性。
在这篇文章中,我想概述一下这两个看似截然不同的范畴--编程和写作--如何可以分离起来,将我们的开发技艺提升到一个新的程度。
等等,技术写作?是的你没看错。我真的置信我们在某种意义上都是作家。我会在这里给你引见写作技巧、倡议以及例子,使你成为更好的开发者和沟通者。
本文包括以下局部:
- 技术写作无处不在
- 什么才是好语法?
- 编写代码注释
- 编写pull request
- 报告bug
- 与客户沟通
- 编写微文案
- 编写无障碍标志
总结
技术写作无处不在
2021年,盛行的Mac Git客户端Tower背后的团队对4000多名开发者停止了调查,发现他们中近50%的人每天花3-6个小时来编写代码。
是的,这是一个针对特定小众群体的调查,但我想我们中的很多人都在这个范围内。无论如何,开发者并非7 * 24都在编写代码,由于正如这个调查所显现的,我们花了很多时间在做其他事情。
这可能包括以下事情:
- 演示一个新功用,
- 记载这个新功用,
- 更新与这个新功用相关的工作方案,或者
- 将支持这个新功用的工作积压。
- 当然,总是有时间上厕所和玩Wordle游戏的。
无论如何,我们通常所做的大局部事情都触及与团队、同事、客户、用户以及其他开发者等人沟通。
所以我们的确花了很多时间经过文字与人类交流,除了经过代码与计算机交流之外。文字是口语言。假如我们能更好地书写文字,我们就能更好地交流。当我们更好地交流时,我们就更有可能得到我们想要的。
而且这还不是全部。一些程序员还喜欢制造他们本人的产品,这意味着他们需求将市场营销作为工作的一局部。技术写作在这方面也起着重要作用。所以没错,我能够十分公正地说,技术写作的确无处不在。
什么才是好语法?
有这么多的编程言语,我们最不想做的就是学习另一种言语。
语法是英语的一个重要组成局部,它释放了沟通的全部潜力。它使我们愈加正式、专业和连接。
让我给你扼要引见一下言语。
英语语法
正如编程言语,英语有一个明白的语法,它从单词开端。
单词是英语的组成局部,它们可分为八个类别:
名词(Nouns)。这些能够是人名、动物、地点、概念和物体的称号。CSS 是前端开发的中心言语之一。
动词(Verbs)。动词传达动作。即便“is”也能够被视为一种动作。
玛西娅早上编写代码,下午回复电子邮件。
形容词(Adjectives)。形容词是我们描绘名词的方式。它们就像元数据,为句子添加更多细节,描画出生动的画面。
CSS是一种文雅而富有诗意的言语。HTML表格是复杂而繁琐的。
盒模型关于了解CSS很重要。
介词(Prepositions)。介词在名词和其他单词之间树立关系,通常表示方向、时间、地点和空间。
**你将你的工作提交到仓库了吗?
关于这个组件,最好的办法是什么?**
我们与真适用户停止了访谈。
副词(Adverbs)。有时分需求更详细的动作描绘,因而我们运用副词,比方“跑得快”和“编译慢”。它们通常以“-ly”结尾。
这绝对是一切想法中最好的。
奇普耐烦地等候戴尔的反应。
团队在项目上勤奋地工作。
连词(Conjunctions)。连词衔接句子中的短语。
CSS用于款式设计,而HTML用于标志。
是的,我编写代码,但我也从事设计工作。
那修复了这个破绽。但是它又引入了一个新的破绽。
过渡词(Transitions)。段落由互相衔接的句子组成,这些句子运用过渡词来衔接。
有很多编程言语。但是,只要少数被应用于网络行业。
首先,克隆该目录。
我喜欢这种办法,但另一方面,我也晓得另一种办法。
代词(Pronouns)。当名词反复呈现时,我们会用代词来替代,比方“他”,“它”和“那个”。
CSS是一种款式表言语。我们运用它来为网站添加款式。
托尼酷爱编码,他每天练习。
我们的客户通晓技术,由于他们理解代码。
将这些言语元素看作UI组件:它们是模块化的局部,你能够挪动它们以构建完好而强健的句子,就像你可能会组装完好而强健的UI一样。一切组件能否一直需求存在?当然不需求!运用所需的局部组装句子,就像你运用界面一样来完成体验。
语气和语调
词汇、标点符号、句子构造和单词选择。这些都是英语的组成要素。我们用它们来分享想法,与朋友和家人交流,并给同事发送电子邮件。
但思索我们信息的声音是至关重要的。一个感慨号就能完整改动信息的语气,这很神奇:
- 我喜欢编程。
- 我喜欢编程!:)
- 我们很容易把语气和语调混杂,反之亦然。
语气关乎我们单词选择的问题,这取决于上下文。例如,针对初学者的教程更有可能运用俚语和非正式的言语来传达友好的语气,而文档可能以正式、严肃和专业的方式撰写,以便直接表达要点。
同样的话,用两种不同的语气编写:
- 有趣:扩展你的社交网络,并随时理解当前盛行的事物。
- 严肃:在最大的社交网络应用程序和在线职位市场上寻觅工作。
- 不测地写出让人感到蔑视、冒犯和不专业的音讯并不稀有。这时语调就发挥了作用。大声朗诵你的音讯,让别人为你朗诵,尝试运用不同的标点符号和句子构造。这就是锤炼语调的办法。
另一个考虑语调的办法是:你的语气从不改动,但你的语调会变化。你的语气相似于你作为一个人的特性,而语调是你在特定状况下的回应方式。
主动语态和被动语态
一个句子一直包含一个动作者、一个动词和一个目的。它们呈现的次第决议了句子是以主动语态还是被动语态书写。
在主动语态中,动作者排在第一位。例如:“CSS绘制背景。”运用主动语态的句子比它们的被动语态愈加简单明了。它们愈加明晰、简约、易于了解——十分合适用于更专业、更直接表达要点的语气。
而在被动语态中,动作者排在最后。这意味着我们的动作者——在这个例子中是CSS——呈现在结尾。就像这样:“背景被CSS绘制”。
读者通常会在心中将被动语态转换为主动语态,这会招致更多的处置时间。假如您曾经听说过运用主动语态更好,那通常就是缘由。技术作者大多数状况下更喜欢运用主动语态,只要极少数例外,比方援用研讨:“有人倡议……”。
但这并不意味着你应该总是追求运用主动语态。假如有效地运用来切换不同的语态——以至在同一段落中——能够使你的内容从一个句子更顺畅地流向下一个句子。
防止犯错
语法触及言语的构造和正确性,关于完成这一点,最好的办法就是快速校正你的文档。去除文档中的拼写错误、语法问题和语义缺陷十分重要。
在本文末尾,我会向你展现专业人士用来防止写作错误的无价工具。显然,如今简直一切东西都内置了拼写检查器;我们的代码编辑器以至有拼写检查和代码检查插件来协助我们预防错误。
但是,假如您正在寻觅一种集一切语法功用于一身的工具,是最普遍运用的工具之一。我没有从中取得任何益处。它只是一个十分棒的工具,许多编辑和作家都用它来写出洁净、明白的内容——就像你可能运用Emmet、eslint或任何其他代码检查器来编写洁净、明白的代码一样。
编写代码注释
我们为其他开发者写的东西会对我们工作的整体质量产生很大的影响,无论是我们在代码中写了什么,如何解释代码,还是如何对一段代码给出反应。
有趣的是,每一种编程言语都有一套规范的特性来写注释。他们应该解释代码在做什么。我指的不是像这样含糊的注释:
red *= 1.2 // Multiply `red` by 1.2 and re-assign it相反,应该运用注释提供更多信息:
red *= 1.2 // Apply a 'reddish' effect to the image一切都与上下文有关。"我在树立什么样的程序?"这正是你应该问本人的问题。
注释应该增加价值
在我们研讨什么是"好的"代码注释之前,这里有两个懒散注释的例子:
const age = 32 // Initialize `age` to 32
filter: blur(32px); /* Create a blur effect with a 32px radius */请记住,注释的目的是为了增加代码的价值,而不是反复代码。假如你无法做到这一点,最好将代码保存原样。这些示例之所以“懒散”,是由于它们仅仅是重述了代码显而易见的操作。在这种状况下,注释是多余的,由于它们在通知我们曾经晓得的东西 - 它们并没有增加价值!
注释应该反映当前代码
在大型项目中,过时的注释并不稀有;我敢说在大多数项目中都存在。
让我们想象一下 David,他是一位程序员,同时也是一个十分酷的人。David想要按字母次第从A到Z对一个字符串列表停止排序,所以他在JavaScript中做了以下显而易见的事情:
cities = sortWords(cities) // sort cities from A to Z接着,David 认识到 sortWords() 实践上是将列表从 Z 到 A 停止排序。这并不是问题,由于他能够简单地反转输出:
cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)不幸的是,David并没有更新他的代码注释。
如今想象一下,假如我没有通知你这个故事,你看到的只是上面的代码。你自然会以为在运转了第二行代码之后,cities 列表将从 Z 到 A 排序!整个紊乱都是由于一个过时的注释所惹起的。
固然这可能是一个夸大的例子,但假如你在紧急截止日期的压力下赶工,相似的事情可能会发作(而且通常也的确会发作)。侥幸的是,这能够经过遵照一个简单的规则来防止:在更改代码的同时更改注释。
这是一条简单的规则,将使你和你的团队免于大量的技术债务。
如今我们晓得写得不好的注释是什么样子的,接着让我们看一些好的例子。
注释应该解释不标准的代码
有时,自然的做事方式并不正确。程序员可能不得不"毁坏 "一下规范,但当他们这样做时,最好留下一个小评论,解释他们的理由:
function addSetEntry(set, value) {
/* Don't return `set.add` because it's not chainable in IE 11. */
set.add(value);
return set;
}这很有用,不是吗?假如你担任检查这段代码,你可能会想在没有注释的状况下纠正它,阐明问题所在。
注释能够明白将来任务
关于注释,另一件有用的事情是供认有更多的工作要做。
// TODO: use a more efficient algorithm
linearSort(ids)这样,你能够坚持对流程的关注。而在以后的某个时间,你(或其别人)能够回来修复它。
注释能够链接到源头
话说,你在 StackOverflow 上找到理解决问题的办法。在复制粘贴该代码后,有时将答案的链接保存下来是一个好习气,这样你能够在未来参考它。
// Adds handling for legacy browsers
// <https://stackoverflow.com/a/XXXXXXX>这很重要,由于处理计划可能会变。晓得你的代码是从哪里来的总是好的,以防它被毁坏。
编写pull request
Pull requests(PRs)是任何项目的根本面。它们是代码检查的中心。假如没有好的描绘,代码检查很快就会成为团队性能的瓶颈。
一个好的PR描绘总结了正在停止的更改以及为什么停止这些更改。大型项目通常有一个拉取恳求模板
## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.
## Types of changes
What types of changes does your code introduce to Appium?
- [ ] Bugfix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- ...
## Checklist
- [ ] I have read the CONTRIBUTING doc
- [ ] I have signed the CLA
- [ ] Lint and unit tests pass locally with my changes
## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…防止含糊的PR标题
请防止下面这些标题:
`Fix build.
Fix bug.
Add patch.`
这些以至没有尝试描绘我们正在处置的构建、错误或补丁是什么。关于构建的哪个局部停止了修复、哪个错误被处理,或者添加了哪个补丁,略微提供一些额外的细节能够大大促进与同事之间更好的沟通和协作。它能够使人们达成共识并站在同一个起点上。
Pull Request 标题通常运用祈使语态书写。它们是整个 Pull Request 的单行摘要,并应描绘 Pull Request 所做的工作。
以下是一些好的示例:
upport custom srcset attributes in NgOptimizedImage
Default image config to 75% image quality
Add explicit selectors for all built-in ControlValueAccessors防止冗余的PR
一个大的PR意味着一个宏大的描绘,没有人愿意检查成百上千行的代码,有时只是为了最终驳回整个代码!
相反,你应该:
- 与你的团队经过 Issues 停止沟通,
- 制定方案,
- 将问题合成成较小的局部,
- 或者每个局部都有本人的 PR 。
- 如今是不是洁净了许多?
在PR正文中提供细节
与 PR 标题不同,PR 正文是包含一切细节的中央,包括:
- 为什么要停止这个 PR?
- 为什么这是最佳办法?
- 该办法任何缺乏之处,以及处理计划
- 相关的 bug 或跟踪单号,基准测试结果等等。
- 报告bug
- Bug 报告是任何项目中最重要的方面之一。一切优秀的项目都树立在用户反应的根底上。通常来说,在无数次测试之后,依然是用户发现了大局部 Bug。用户也是巨大的理想主义者,有时他们会提出功用方面的想法,请倾听他们的意见!
关于技术项目,一切这些都是经过报告 issue 来完成的。一个写得好的 issue 能够让另一个开发人员轻松地找到问题并停止回应。
比方
### Subject of the issue
Describe your issue here.
### Your environment
* version of angular-translate
* version of angular
* which browser and its version
### Steps to reproduce
Tell us how to reproduce this issue.
### Expected behavior
Tell us what should happen.
### Actual behavior
Tell us what happens instead.搜集截图
假如是 CLI 程序的截图,请确保文本明晰可见。假如是 UI 程序,请确保截图捕捉到正确的元素和状态。
你可能需求捕获一个实践的交互过程来展现问题。假如是这种状况,请尝试运用屏幕录制工具来录制 GIF 动画。
如何重现问题
当 Bug 在程序员的电脑上呈现时,处理起来要容易得多。这就是为什么一个好的提交信息应该附带可以准确重现问题的步骤。
下面是一个例子:
Update: you can actually reproduce this error with objects:
<div *ngFor="let value of objs; let i = index">
<input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
</div>
export class OneComponent {
obj = {v: '0'};
objs = [this.obj, this.obj, this.obj, this.obj];
setObj(i: number, value: string) {
this.objs[i] = {v: value};
}
}
The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.倡议缘由
作为捕获 Bug 的人,你能够为为何呈现这个 Bug 提供一些潜在的缘由。或许 Bug 只在遇到某个特定事情后发作,或者只在挪动设备上发作。
探究源码也没有什么害处,或许能够找出招致问题的缘由。然后,你的 issue 会更快地被关闭,而且你有可能被分配到相关的PR。
与客户沟通
你可能是一名独立的自在职业者,或者可能是一个小团队里的主要开发人员。在任何一种状况下,假定你担任与客户在项目上停止沟通。
现往常,程序员的呆板印象是我们不擅长沟通。我们以过于技术化的术语表达本人,通知他人什么是可能的,什么是不可能的,以至当有人质疑我们的办法时,我们会变得有防御性。
那么,如何缓解这种呆板印象?讯问客户想要什么,并一直听取他们的反应。以下是如何做到这一点的办法。
讯问正确的问题
首先要确保你和客户的想法是分歧的:
- 您的目的受众是谁?
- 网站的目的是什么?
- 您最近的竞争对手是谁,他们做对了什么?
发问也是以积极的方式写作的好办法,特别是不同意客户的反应或决策的状况下。发问迫使对方支持本人的主张,而不是经过为本人的立场辩护来攻击他们: - 您对此能否称心,即便它带来额外的性能本钱?
- 挪动组件能否有助于更好地完成我们的目的?
- 太好了,谁担任在启动后维护它?
- 您晓得这两种颜色之间的比照能否契合 WCAG AA 规范吗?
- 采购本人
假如你要向潜在的客户停止采购,你就需求压服他们雇用你。客户为什么应该选择你?提出以下内容很重要: - 你是谁
- 你在做什么
- 为什么你很合适这份工作?
- 你所做过的相关工作的链接
一旦你得到了工作并需求起草合同,请记住没有比一堆法律术语更令人生畏的内容了。即便它是为设计项目编写的
你对细节的关注可能是你和其他开发者赢取同一项目的区别。依据我的经历,客户容易雇用他们以为会喜欢与之协作的开发者,而不是技术上最有才能或经历最丰厚的开发者。
编写微文案
微文案是编写用户友好的UI信息的一门艺术,例如错误音讯。我敢打赌,作为开发人员,你有时不得不编写错误音讯,由于它们不断被放置到发布时间。
这可能就是为什么我们有时会看到这样的错误:
Error: Unexpected input (Code 693)
错误是你最不希望用户遇到的问题。但它们的确会发作,我们无能为力。以下是一些进步微文案技艺的技巧。
防止技术术语
大多数人不晓得什么是效劳器,而程序员100%晓得。这就是为什么在错误音讯中会看到像 API 或超时执行这样的不常见术语。
除非你面对的是技术客户或用户群体,否则你的大局部用户可能没有上过计算机科学课程,不晓得互联网是如何工作的,也不晓得为什么某个特定的东西不起作用。
因而,一个好的错误音讯不应该解释为什么呈现问题,由于这样的解释可能需求运用令人生畏的技术术语。这就是为什么防止运用技术术语十分重要。
不要责怪用户
想象一下:我正在尝试登录你的平台。我翻开阅读器,访问你的网站,输入我的细致信息。然后我被告知:“您的电子邮件/密码不正确。”
虽然以为这个信息是敌对的似乎很夸大,但它在潜认识里让我觉得本人很愚笨。微文案表示,千万不要责怪用户。尝试将你的音讯更改为责备性更少的内容,例如:“负疚,该电子邮件密码组合不正确。我们能够协助您恢复帐户。”
我还想补充一点,防止运用全大写字母和感慨号十分重要!当然,它们能够用来传达兴奋的心情,但在微文案中运用会给用户带来一种敌对感。
不要让用户手足无措
在微文案中运用诙谐是个好主见!它能够缓解心情,是减少负面影响的简双方法。
但是,假如你运用不当,诙谐也有可能会让用户感到蔑视和凌辱。这是一个宏大的风险。
不要不顾一切地去开玩笑 - 强行诙谐可能比不诙谐更糟糕。假如你不肯定,请坚持耿直的表情。
编写无障碍标志
我们能够轻松地撰写一篇关于无障碍性,以及与技术写作相关的文章。事实上,无障碍性通常包含在内容款式指南中
作为开发者,你可能曾经十分理解无障碍性。你以至可能是很勤奋的开发者之一,将无障碍性作为工作流程的中心局部。但是,无论我们觉得无障碍性是多么重要,无障碍性依然是低优先级。
因而,假如你发现本人正在将别人的文案编写到代码中,为其他开发者编写文档,以至本人编写UI文案,要留意一些根本的无障碍最佳理论,由于它们完善了一切其他技术写作的倡议。
一些需求留意的事项包括:
尽可能运用语义标签例如
- 遵照逻辑的标题构造
- 为图片添加 alt 文本
留意行内语义
总结
这些是展现技术写作和开发互相关联的六种方式。固然这些例子和倡议可能不是什么深邃的技术,但我希望你可以发现它们有用,无论是与其他开发人员协作、维护本人的工作、在紧急状况下编写本人的副本,或者起草项目提案等等。
评论
登录后参与技术讨论,分享你的经验与见解。
登录 / 注册暂无评论