目录

工程师和文档

目录

你们平时会给代码写注释码?

我始终认为,那些代码和文档都写得非常好的工程师,值得我们珍视。

代码和文字表达实际上是相通的。遗憾的是,许多工程师虽能编写优雅的代码,却往往忽视文档和注释的撰写。这是我发现的多数理工科男性的共性: 不喜欢,甚至鄙视书写文档。

我个人非常重视文档。这主要是因为,我在职业生涯中因同事忽视文档编写而走了许多弯路。清晰的文档不仅需要简洁的文字,有时候辅以图示能极大提高理解力。此外,避免冗长,因为大多数人的阅读耐心不超过五分钟。另外文档的格式也很关键,包括标点、中英文切换、段落分隔等,应确保过去和将来的文档格式一致,避免阅读障碍。

因此,我们应该珍惜那些注重文档质量的工程师,他们不仅对团队做出了贡献,还极其注重细节。最后就是,为什么写这么一篇文章,这是因为我刚刚读了一篇冗长、难以理解的内部文档,我读了三遍仍难以完全明白,是真的对不把文档写清楚的工程师有点失望😔。

警告
本文最后更新于 2017年2月1日,文中内容可能已过时,请谨慎参考。