知识卡片

普通读书笔记卡 · 6991.r.2.l · 生成模型:未记录

文档格式要兼顾源码与生成物

理解等级:中级

注释既可能在编辑器里阅读,也可能被工具生成网页。大量转义和布局标签会妨碍源码阅读,但适当的代码块、链接和列表也可能对生成文档必要。应选能同时表达语义并便于维护的格式,再检查生成结果,不把“工具负责呈现”理解成所有Javadoc HTML都不合法或都应删除。

这张卡片看不懂?

已有反馈 · 0 条

    还没有人提交反馈。

    在整书笔记中的位置

    原书出处 · 2 处

    参考来源

    - 位置:《代码整洁之道》全书 · 第4章 注释,spine013单元009;来源项目book-sources,extracted/代码整洁之道/_epub-src/OEBPS/Text/part0011.xhtml。 - 结论依据:原文任务使用说明被转义标记包围而难读,支持权衡两种阅读场景;此处只评表达负担,没有将合法标记一概判错。未在本机运行示例或改变环境。 - 原始内容:因为HTML 注释的存在而变得难以卒读。如果注释将由某种工具(例如Javadoc)抽取出来,呈现到网页,那么该是工具而非程序员来负责给注释加上合适的HTML标签。 /** * Task to run fit tests. * Th