Context: Code annotations have gained widespread popularity in programming languages, offering developers the ability to attach metadata to code elements to define custom behaviors. Many modern frameworks and APIs use annotations to keep integration less verbose and located nearer to the corresponding code element. Despite these advantages, practitioners' anecdotal evidence suggests that annotations might negatively affect code readability. Objective: To better understand this effect, this paper systematically investigates the relationship between code annotations and code readability. Method: In a survey with software developers (n=332), we present 15 pairs of Java code snippets with and without code annotations. These pairs were designed considering five categories of annotation used in real-world Java frameworks and APIs. Survey participants selected the code snippet they considered more readable for each pair and answered an open question about how annotations affect the code's readability. Results: Preferences were scattered for all categories of annotation usage, revealing no consensus among participants. The answers were spread even when segregated by participants' programming or annotation-related experience. Nevertheless, some participants showed a consistent preference in favor or against annotations across all categories, which may indicate a personal preference. Our qualitative analysis of the open-ended questions revealed that participants often praise annotation impacts on design, maintainability, and productivity but expressed contrasting views on understandability and code clarity. Conclusions: Software developers and API designers can consider our results when deciding whether to use annotations, equipped with the insight that developers express contrasting views of the annotations' impact on code readability.

翻译：上下文：代码注解在编程语言中已广泛普及，使开发者能够将元数据附加到代码元素上以定义自定义行为。许多现代框架和API使用注解来减少集成时的冗余性，并使注解更贴近对应的代码元素。尽管有这些优势，但来自实践者的轶事证据表明，注解可能会对代码可读性产生负面影响。目标：为更深入理解这一影响，本文系统性地研究了代码注解与代码可读性之间的关系。方法：在一项面向软件开发者的调查（n=332）中，我们展示了15对带有和不带代码注解的Java代码片段。这些代码对的设计涵盖了真实Java框架和API中使用的五类注解。调查参与者为每个代码对选择他们认为更具可读性的片段，并回答一个关于注解如何影响代码可读性的开放式问题。结果：所有注解使用类别的偏好分布分散，参与者之间未达成共识。即便按参与者的编程或注解相关经验进行分组后，答案依然分散。尽管如此，部分参与者在所有注解类别中表现出始终支持或反对注解的偏好，这可能反映了个人倾向。我们对开放式问题的定性分析显示，参与者常称赞注解对设计、可维护性和生产力的积极影响，但对可理解性和代码清晰度则表达了矛盾的观点。结论：软件开发者与API设计者在决定是否使用注解时，可参考我们的结果——需认识到开发者对注解影响代码可读性持有相反观点。