[论文解读] The Case for API Communicability Evaluation: Introducing API-SI with Examples from Keras

Luiz Marques Afonso, João Antonio Marcondes Dutra Bastos+2 more|arXiv (Cornell University)|Aug 17, 2018

Software Engineering Research参考文献 24被引用 4

一句话总结

本文提出 API-SI，一种符号学评估方法，通过分析 API 的结构、行为和文档中的符号，评估其在传达设计意图方面的有效性。在 Keras 上的应用表明，显性和隐性符号如何影响开发者对 API 的理解，为提升 API 的可沟通性提供了一项实用工具，并可补充传统软件工程中的可用性研究。

ABSTRACT

In addition to their vital role in professional software development, Application Programming Interfaces (APIs) are now increasingly used by non-professional programmers, including end users, scientists and experts from other domains. Therefore, good APIs must meet old and new user requirements. Most of the re-search on API evaluation and design derives from user-centered, cognitive perspectives on human-computer interaction. As an alternative, we present a lower-threshold variant of a previously proposed semiotic API evaluation tool. We illustrate the procedures and power of this variant, called API Signification Inspection (API-SI), with Keras, a Deep Learning API. The illustration also shows how the method can complement and fertilize API usability studies. Additionally, API-SI is packaged as an introductory semiotic tool that API designers and researchers can use to evaluate the communication of design intent and product rationale to other programmers through implicit and explicit signs thereof, encountered in the API structure, behavior and documentation.

研究动机与目标

• 为解决日益增长的需求：API 不仅需对专业开发者可理解，也需对非专业人员（如科学家和领域专家）可理解。
• 提出一种低门槛的符号学 API 评估变体，聚焦于通过 API 结构、行为和文档中的符号来传达设计意图的可沟通性。
• 为 API 设计师和研究人员提供一种实用且易用的工具，以评估 API 在传达其设计理由和意图方面的表现。
• 展示符号学分析如何补充并丰富传统的可用性与基于认知的 API 评估方法。

提出的方法

• API-SI 运用符号学理论，分析 API 中的显性和隐性符号，重点关注设计决策如何被传达给开发者。
• 该方法评估三个维度：结构符号（如类名和方法名）、行为符号（如方法行为和返回类型）以及文档符号（如注释和示例）。
• 采用结构化检查流程，评估者基于符号的指谓意义（即其对 API 目的和设计的暗示或暗示内容）来解释符号。
• 该方法基于皮尔斯符号学理论，区分图像符号（相似性）、指示符号（因果关联）和象征符号（基于惯例的意义）。
• API-SI 设计为入门级工具，使符号学非专家也能系统性地应用于 API 评估。
• 通过 Keras（一个深度学习 API）的案例研究对方法进行验证，以展示其实际应用与洞察价值。

实验结果

研究问题

• RQ1 API 符号在多大程度上传达了设计意图和产品设计理由给开发者？
• RQ2 符号学分析在多大程度上能揭示 API 结构和行为中隐藏或隐含的设计决策？
• RQ3 API-SI 与现有可用性或基于认知的 API 评估方法相比或互补如何？
• RQ4 非符号学专家能否在真实世界 API（如 Keras）上一致且有意义地应用 API-SI？
• RQ5 Keras 的 API 结构、行为和文档中，哪些具体符号促进了或阻碍了可沟通性？

主要发现

• API-SI 成功识别出 Keras 中特定命名惯例和方法行为如何隐式地向开发者传达设计模式和意图。
• 该方法揭示，Keras 中某些方法名（如 'Dense' 和 'Conv2D'）作为图像符号，通过视觉上暗示其功能，增强了可发现性。
• 文档符号（如代码示例和 docstring 清晰度）被发现显著影响 Keras API 的可沟通性感知。
• 分析揭示了行为符号（如意外的返回类型）与结构符号之间存在不一致，导致开发者困惑。
• API-SI 展示了在发现传统可用性测试可能遗漏的 API 中细微沟通失效方面的实际效用。
• 案例研究证实，符号学评估可提供可操作的洞察，用于改进 API 设计，超越语法正确性或功能正确性。