一、什么样的文档(代码)叫做“好”?
任何一篇文档,目标都是给别人看懂。
任何一段代码,首先也都是别人能看爽了才是目标。
以上述“世界观”为准,很容易得到文档(代码)好不好的结论。
以80后小时候读的连环画为例,它就是优秀文档的典范。
像连环画这样优秀的文档,主要具备以下几个特点:
1.长篇被分成小节。
2.小节中关键页有图。
3.描述言简意赅。
4.页数固定不多。
典型地,如果在写文档(代码)时,能够做到上述四点,都是优秀的。
比如:
PHP文档造福了多少PHP程序员,让PHP这门语言流芳百世、追随者众多。在PHP文档中,每一小节都进行了特别归类; 在关键位置还有不少例子代码; 每个方法的作用也是言简意赅; 每一小节的数量都不是很多。
再来看nginx代码,完全是一个大型服务端软件构建的一个范例。只看src目录中的源码,从一开始就分成了core、event、http、mail、misc、os,这样相当清晰明了的层级结构和定义,让后续很多事情方便扩展; 每一部分的代码都能够让读者一眼看明白是做什么的; 每个细节的方法长度也不是特别长; 每个分类里的内容也相对是固定的,后续的改进都是在plugin上比较多。
二、几种实际的土办法提高文档(代码)能力
在上述建立好了对好文档(好代码)的世界观之后,下面再分享一些总结出来的套路,如果前面世界观没理解透,只把这里的土办法理解了,也能写出来容易读的文档(代码)。
办法一、写文档先写段落标题,写代码先建分类目录(java叫做package)。
在一切开始之前,如果无法下笔,则先想想要写代码架子都有哪些。
办法二、一级段落不要超过5个。
这纯粹是个经验值,实际超过3个的时候已经开始有些遗忘前面的了。套在代码上,不要超过5种主要功能的目录,像nginx有6个,不过os和misc基本上都是固定不改的东西,所以常动的也只有4个而已。
办法三、不要没有段落画大饼
这和办法二是相反的,因为人脑对内容的吸收是有阶梯的,越往后的内容越难记住。所以在适当的时候要歇一歇。套在代码上,就是不要搞一个大类,什么都能干。
办法四、尽可能让文档(代码)先少后多
这个办法是指,让读代码的人先看一小部分,慢慢再“勾引”读者不断地深入。
好了,上面的办法都实施之后,一手好湿就应该不远了。
转载自五四陈科学院[http://www.54chen.com]
分享到:
相关推荐
代码附数据集加载方式,文档包括案例完整流程:DNN/CNN结构设计、模型参数保存、断点续训、acc/loss可视化过程,最好一次epoch的模型参数保存。
基于深度学习实现试卷手写文字擦除源码+模型文件+说明文档.zip 【项目资源说明】 训练数据: 增强仅使用横向翻转和小角度旋转,保留文字的先验 随机crop成512x512的patch进行训练 训练分为两阶段: 第一阶段损失...
一个有用的脱机手写识别源代码!有文档说明及源代码
作业一:GMM 手写高斯混合模型算法,用期望最大算法(EM)实现。 作业二:SVM 手写支持向量机算法,用序列最小最优化算法(SMO)实现。 作业三:CNN 手写卷积神经网络算法,包括前向传播、反向传播、参数更新。 1、...
科翰SOAOFFICE 2007文档控件(绿色版)是一款免安装卸载、免费使用的网络文档中间件。 下载地址:http://www.kehansoft.com/web/shared/download.asp?id=1 1.独特的文档安全性:防下载、防拷贝、防粘贴、防篡改、防...
动手实现了一个第一人称视角的编写方式,以前一直都用的unity自带的standardassets里面的第一人称视角预制体,现在也能自己写出来这种视角了,根据里面的文档来写每个人都可以做到,文档还介绍了一些简单的知识点,...
你想在你的Word文档中写一手漂亮文字吗? --请用EJun手写签名 本软件用于在Word,Excel中加入手写签名,文件批注,印章。独特的手写板, 让你写一手漂亮的文字,落一个精彩的签名。个性签名也可用图形编辑软件 ...
本代码使用c++实现神经网络的一个简单应用,不借助任何框架。目的是加深对神经网络工作流程的理解。目前提供使用mnist手写数据集的识别,识别准确率大概在95%左右。 - 不懂运行,下载完可以私聊问,可远程教学 该...
作为一个长期混迹于CSDN社区的人,我对很多拥有高访问量的博主钦佩不已,特别是在参加了CSDN在举办“2014 CSDN博文大赛”及“2015 CSDN-Markdown博文大赛”活动之后。我看到活动中的一些参赛作品条理清晰、文笔流畅...
EasyPoi的编写其实是一次意外,之前我不太愿意写导入导出,因为代码号复杂,每次一个Excel 都要写几百行,仅有少量的复用,一次需要写许多的导入导出,又没有人手,正好看到了Jeecg对应Poi的一个封装,但是他的封装比较简单,...
我自己动手写的一个用户管理程序,有详细的说明和代码,都在压缩包里面。数据库也在。
该资源内项目源码是个人的毕设,代码都测试ok,都是运行成功后才上传资源,答辩评审平均分达到96分,放心下载使用! <项目介绍> 1、该资源内项目代码都经过测试运行成功,功能ok的情况下才上传的,请放心下载使用! ...
基于python实现手写痕迹文档图像摩尔纹消除源码+项目运行说明.zip 二、数据分析 **数据划分**:使用1000张做为训练集,81张作为验证集。 官方提供了训练集1081对,测试集A、B各200张。包含以下几个特征: 1.图像...
这是大二初学java时写的一个手写识别小软件。 这里包含了整个程序的源代码,《概要设计说明书》,javadoc 和 UML类图。 Version: 1.0 压缩包中包含了: 1.任务综合报告:概要设计说明书.docx 2.程序源代码文件:...
此压缩包里含有开发文档的详细描述,源代码每一处都有详细的解释,对于想练练手的java程序员新手绝对是莫大的帮助
DevChat 是一个开源平台,使开发人员能够更有效地将 AI 集成到代码生成和文档中。DevChat 旨在超越简单的代码自动完成和对代码片段的有限操作。DevChat 为开发人员提供了一种非常实用和有效的方式来与大型语言模型 ...
HTML5开发精要与实例详解(完整版源代码含说明文档)内容分为两大部分:第一部分通过一系列中大型案例全方位对html 5的各个重要知识点进行了详细的讲解,每个案例包含案例概述、页面效果展示、案例所涉及主要知识点...
于是一怒之下,自己动手丰衣足食,于是就自己用Swing写了一个基于数据库的自动化生成工具,支持MySQL、Oracle、SQLServce、PostgreSQL,完美支持JPA注解,可以同时生成Entity和DTO等,可以自动去除表前缀,支持单个...
不管你以何种方式发现了文档的不足,或是丢失对某一特性的描述,那么你能做的最好的事情莫过于去研究它并把文档写出来。 该文档 xdoc 格式的源码文件可通过 项目的 Git 代码库来获取。Fork 该源码库,做出更新,...
①、内置支持多达 27 种语法高亮度显示(包括各种常见的源代码、脚本,能够很好地支持 .nfo 文件查看),还支持自定义语言; ②、可自动检测文件类型,根据关键字显示节点,节点可自由折叠/打开,还可显示缩进引导线...