知识卡片
文档格式要兼顾源码与生成物
注释既可能在编辑器里阅读,也可能被工具生成网页。大量转义和布局标签会妨碍源码阅读,但适当的代码块、链接和列表也可能对生成文档必要。应选能同时表达语义并便于维护的格式,再检查生成结果,不把“工具负责呈现”理解成所有Javadoc HTML都不合法或都应删除。
这张卡片看不懂?
这张卡片已通过人工审查,不再接受失败反馈。
已有反馈 · 0 条
还没有人提交反馈。
在整书笔记中的位置
- · 第4章 注释
原书出处 · 2 处
- 第4章 注释 4.4.13 HTML注释 · 查看原书依据
如果注释将由某种工具
- 第16章 重构SerialDate 16.2 让它做对 · 查看原书依据
一个源文件里面有多种语言
参考来源
- 位置:《代码整洁之道》全书 · 第4章 注释,spine013单元009;来源项目book-sources,extracted/代码整洁之道/_epub-src/OEBPS/Text/part0011.xhtml。
- 结论依据:原文任务使用说明被转义标记包围而难读,支持权衡两种阅读场景;此处只评表达负担,没有将合法标记一概判错。未在本机运行示例或改变环境。
- 原始内容:因为HTML 注释的存在而变得难以卒读。如果注释将由某种工具(例如Javadoc)抽取出来,呈现到网页,那么该是工具而非程序员来负责给注释加上合适的HTML标签。 /** * Task to run fit tests. * Th