模板设计与管理

MediaWiki:Testtoc.js

模板是Wiki编写的强力工具，Wiki重要的基础设施。模板可以让用户重用已有设计，轻松的编写统一风格的复杂页面。

本文关注模板的设计和管理。如果你要了解如何使用模板，请参阅：BWiki模板帮助、帮助;萌娘百科-模板入门、模板帮助;MediaWiki模板帮助。此外请参考其他Wiki的模板，实例是最好的老师。

设计原则

我们推荐引入软件工程领域的几个原则，它们多年来指导了大量软件的开发。

KISS（Keep It Simple Stupid）

KISS原则：设计应当保持简洁、单纯，不加入非必要的复杂性。

• 不复杂化代码
• 不过度设计
• 不过早优化
• 不断重构

KISS原则最后的Stupid并没有任何隐涵开发者是愚蠢的含义，而是相反的，要求模板的设计让人易于理解。

再复杂的模板，其使用者和未来的维护者也是广泛的BWiki用户。我们不能假设所有用户都是MediaWiki的使用专家。 设计和开发模板时，每多使用一个特性，就引入了一个新知识。这会增加对维护者的要求，使用者也更难理解模板的行为和工作原理。 缺少使用和维护的模板会逐渐被抛弃、替换。

案例一：某Wiki翻新。去年底开始，小伙伴们接手了一个多年没有维护的Wiki。

在检查基础设施时，发现了各个历史时期引入的模板模块，一部分已经弃用或从未投入使用，一部分已经无法正常工作。它们的功能强大，依赖关系繁复冗杂，但其使用的数据和计算公式已经过时。

从大量的github项目和Wiki已有数据来看，早期的建设者非常熟悉游戏实现和MediaWiki的高级特性。但是他们宏大的自动化构想只完成了一半，目前的维护者没有能力，也没有足够的时间从复杂的游戏中解析所有数据完成这个计划。即使我们能够完成自动化，数年后如果无法维持更新，这些自动化设施也会被后继维护者简化和移除。

因此，我们的建设计划是对维护者友好，尽量使用简单的特性。比如我们能够提取物品信息，但没有使用基于JSON存储数据再显示的方案。因为JSON方案对自动化友好，但是其他维护者难以上手维护数据。此外，所有物品都使用信息栏模板来展示大量属性。由于游戏机制复杂属性繁多，这个遗留模板硬生生写了几千行，逐一处理了各种属性的解析、存储和显示。大量模板和页面依赖于信息栏模板的结果，这让翻新工作非常棘手。

案例二：某Wiki事件。一个Wiki由于全站自动化，除了极少数维护者外，其他人即使编辑了页面也会被定期的自动化更新覆盖编辑。这使得所属Wiki平台紧急出台了相关规定，限制高权限用户的行为和自动化带来的问题。比如技术架构应该对路人随机的编辑友好，避免“自动化”隐式的剥夺大多数人的编辑权限。

高水平的基础设施可以为Wiki带来大量便利，降低编辑门槛，但同时提高了基础设施的维护要求。因此在进行高技术基建时，需要谨慎设计。

案例三：一个导航模板。在一个wiki维护中，已有的导航盒模板功能丰富，实现复杂。但是Wiki对导航的需求很少，因此小伙伴决定改造Paradox CSL Wiki的Navbox以替代早期引入的导航盒模板，这导致了模板:导航的产生。

新模板使用了更简单的实现满足了需求。此时导航盒模板的缺点：实现复杂、过度设计。 相应的，很多Wiki对导航的需求更多更复杂。新模板的缺点明显：缺乏功能、设计不足。

这不是说导航盒不好。而是针对简单的导航需求，Navbox使用了更简单的设计和实现，需要更少的知识和理解成本。 这不是说新模板不好。而是针对复杂的导航需求，导航盒提供了更充分的设计和实现，提供丰富的功能和灵活表现。

单一功能

简单来说，建议每个模板只提供一个功能。这源于面向对象设计中的SOLID原则。

BWiki中，经常见到一些模板提供多个功能。这直接带来以下缺点：

• 使用难：功能复杂，特别是涉及状态或标签开闭的。
• 理解难：理解一个模板意味着：需要理解十个
• 维护难：难以确定修改的影响。一个地方出错，其他功能也会受影响。
• 测试难：测试一个功能很简单，测试一堆可能相互影响的功能很困难，需要更多用例保证正确性。

案例一：模板:板块。它提供了13个模板的功能。

如果你只需要其中一个功能，也不得不了解整个模板。 在修改其中一个功能时，还要考虑是否影响其他的其他功能/样式。

如果修改其中一个子功能时出现了语法错误，导致分配功能的Switch提前结束，可能的异常表现是位于子功能代码后边的所有功能失效。 这会对分析、定位问题带来很大困难。 如果这些子功能相互依赖，将很难调试、修改，这是维护者的噩梦。

比如，星穹铁道的图标模板就是这样。当其他页面编辑异常时，无法第一时间定位问题。定位到图标模板后，由于它拼装了不同功能且有大量的行内CSS，需要花费较长时间阅读检查才能修复。在修复后，由于影响到多个功能，仍需逐个测试保证代码正确性。

案例二：模板:施工中。它基于信息模板实现，仅为页面标注施工中状态。

其中，信息模板为所有提示信息提供支持，提供框架而非固定内容。施工中模板可以简单的定制显示效果和内容。 即使维护者不了解信息模板的实现，也不会影响他修改施工中模板的细节。

同样基于信息模板的还有风险、协议、弃用等模板。每个模板只关注实现其自身功能，无需关注样式细节和显示逻辑。

虽然信息模板使用了早年Bootstarp的经典风格，但可以通过修改信息模板，便捷的调整所有相关模板的显示风格。

管理原则

为了更好的组织、管理和优化模板，可以尝试使用以下原则。

开放编辑

作为Wiki，应尽量开放所有页面的编辑。

保护模板页面应谨慎，并给出原因。

一个广泛使用的模板显然应当加以保护，使其不被贸然编辑。比如有没有充分测试的更改可能导致大量页面显示错误，更改和修正也会给wiki服务器带来额外负载。比如更改常用模板的参数和使用方法时，如果没有充分讨论和告知就可能带来很多意外，造成不知情编者的困惑甚至被错误使用。

提供文档

模板应当提供文档，包括使用文档和设计文档。

使用文档面向所有编辑者，简洁清晰地说明使用方式，并给出示例。

设计文档面向模板维护者。比如给出模板的设计目标，技术方案和细节说明。

经典段子：这段代码在三个月前只有我和上帝能看懂。现在嘛，只有上帝能看懂了。

充分测试

在编辑模板前，应当尽量充分的测试。

比如利用临时的沙盒模板和页面测试。

被广泛使用的模板一旦出错将会影响大量页面，这会降低读者体验。此外，修复时还要浪费服务器资源刷新大量页面。

统一格式

模板应当有统一的格式。容易阅读和维护。

比如<noinclude>统一放在模板尾部/头部。

比如换行风格，是灵活换行还是统一使用注释换行？复杂的HTML和解析器函数需要良好的换行才容易阅读。否则很容易把简单的模板写成天书。

比如统一组织模板的帮助文档。不应该分散在不同命名空间……这会给阅读者和维护者带来困惑。

独立文档页模式

参见Wikipedia:模板文件頁模式。上文节选：

模板文档页模式是一种机制，用来将模板帮助文档从模板源代码中安全地分离成为帮助文档页面。
这能够使得模板本身处于完全保护状态下，而说明部分保持未保护状态，让每个人仍然可以编辑模板帮助文档。

本Wiki使用 {{帮助:{{PAGENAME}}}} 来提供这一模式。将模板和帮助文档分开在两个命名空间，就不会在模板命名空间看到大量文档页面，也可以在帮助空间快速浏览模板文档。

此外，skyrim wiki使用{{模板帮助}}提供文档框架并将模板放在帮助空间，csl2 wiki利用类似的{{模板帮助}}提供文档框架，将文档保存为模板的子页面。

模板导航

使用单独的页面综述Wiki模板。

典型的如csl wiki中的帮助:模板。这个页面有一个模板导航，还列出并简介已有模板。

这可以让有经验的编辑者快速熟悉wiki基础设施，让新手能便捷地找到文档。