Context: Code annotation is a feature to define custom metadata about programming elements. Many modern frameworks and APIs use annotations to keep integration less verbose and closer to the corresponding code element. However, contrary to the initial intent, practitioners often complain about the negative impacts of annotations on code readability. Objective: We conducted a survey where participants compared the readability of code snippets with and without annotations to understand this

more »

... tion further. Method: We designed the code snippet pairs considering five different usage categories for annotations present on frameworks and APIs used on real-world projects. Results: The survey received 338 valid answers from diverse participants. Surprisingly, the answers to all the questions had a normal distribution, and none of them revealed a scenario in which the usage of code annotations could be considered better or worse for readability. Additionally, we could not find a correlation between any aspect of the participants' programming or annotation-related experience and their answers. We also found biased perceptions in favor or against annotations. Our qualitative analysis also revealed contrasting opinions about the effects on code readability. Participants praised the impacts on design, maintainability, and productivity. However, understandability and code clarity had contrasting views. Conclusions: Developers and API designers can use our results when deciding whether to use annotations, considering there is no evidence of a generally positive or negative impact on readability and the existence of biased views, even with a personal bias that might suggest differently.