Skip to main content
SpringerLink
Log in

How do annotations affect Java code readability?

  • Published:
Empirical Software Engineering Aims and scope Submit manuscript

Abstract

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.

This is a preview of subscription content, log in via an institution to check access.

Access this article

Log in via an institution

Price excludes VAT (USA)
Tax calculation will be finalised during checkout.

Instant access to the full article PDF.

Institutional subscriptions

Fig. 1
Fig. 2
Fig. 3
Fig. 4
Fig. 5
Fig. 6
Fig. 7

Similar content being viewed by others

Data Availability

All the data related to this research, including an anonymized dataset, scripts, and the questionnaire, is available in the Zenodo (https://doi.org/10.5281/zenodo.5396378) open data archive.

Notes

  1. http://projectlombok.org

  2. https://github.com/metaisbeta/schema-organizer

  3. https://www.tabnine.com/code

  4. https://en.wikipedia.org/wiki/Marker_interface_pattern

  5. https://doi.org/10.5281/zenodo.5396378

  6. This notation denotes the number of mentions in which the impact was classified as positive or negative.

References

  • Baltes S, Diehl S (2016) Worse than spam: issues in sampling software developers. In: 10th international symposium on empirical software engineering and measurement, ACM, New York, USA, ESEM’16. https://doi.org/10.1145/2961111.2962628

  • Beelders TR, du Plessis JPL (2016) Syntax highlighting as an influencing factor when reading and comprehending source code. Journal of Eye Movement Research 9(1)

  • Benjamini Y, Hochberg Y (1995) Controlling the false discovery rate: a practical and powerful approach to multiple testing. J Roy Stat Soc: Ser B (Methodol) 57(1):289–300

    Article  MathSciNet  Google Scholar 

  • Bloch J (2016) Effective Java. Pearson Education

  • Boehm B, Basili VR (2001) Software defect reduction top 10 list. Computer 34(1):135–137. https://doi.org/10.1109/2.962984

    Article  Google Scholar 

  • Briand L, El Emam K, Morasca S (1996) On the application of measurement theory in software engineering. Empir Softw Eng 1(1):61–88

    Article  Google Scholar 

  • Bugayenko Y (2016) Java annotations are a big mistake. Personal blog: https://www.yegor256.com/2016/04/12/java-annotations-are-evil.html

  • Buse RP, Weimer WR (2010) Learning a metric for code readability. IEEE Trans Software Eng 36(4):546–558. https://doi.org/10.1109/TSE.2009.70

    Article  Google Scholar 

  • Buttler DJ (2008) Java metadata facility. Encyclopedia of Database Systems, November 1, 2009, pp 1580. https://www.osti.gov/biblio/973644

  • Chen N (2006) Convention over configuration. http://softwareengineering.vazexqi.com/files/pattern.html

  • Córdoba-Sánchez I, de Lara J (2016) Ann: a domain-specific language for the effective design and validation of Java annotations. Comput Lang Syst Struct 45:164–190

    Google Scholar 

  • Damyanov I, Holmes N (2004) Metadata driven code generation using .net framework. In: Proceedings of the 5th international conference on Computer systems and technologies, ACM, pp 1–6

  • Dietl W, Dietzel S, Ernst MD, Muşlu K, Schiller TW (2011) Building and using pluggable type-checkers. In: Proceedings of the 33rd international conference on software engineering, pp 681–69

  • Ernst MD (2008) Type annotations specification. JSR 308: http://types.cs.washington.edu/jsr308/

  • Fernandes C, Ribeiro D, Guerra E, Nakao E (2010) Xml, annotations and database: a comparative study of metadata definition strategies for frameworks. May 19–20, Vila do Conde p 115

  • Guerra E (2016) Design patterns for annotation-based APIs. In: Proceedings of the 11th Latin-American conference on pattern languages of programming, SugarLoafPLoP, vol 16, p 9

  • Guerra E, Fernandes C (2013) A qualitative and quantitative analysis on metadata-based frameworks usage. In: International conference on computational science and its applications, Springer, pp 375–390

  • Guerra E, Silva J, Silveira F, Fernandes C (2008) Using metadata in aspect-oriented frameworks. Contemporary Modularization Techniques (ACoM 08) p 13

  • Guerra E, Cardoso M, Silva J, Fernandes C (2010a) Idioms for code annotations in the java language. In: Proceedings of the 8th Latin American conference on pattern languages of programs, Association for Computing Machinery, New York, USA, SugarLoafPLoP’10. https://doi.org/10.1145/2581507.2581514

  • Guerra E, Fernandes C, Silveira FF (2010b) Architectural patterns for metadata-based frameworks usage. In: Proceedings of the 17th conference on pattern languages of programs, pp 1–25

  • Guerra E, Alves F, Kulesza U, Fernandes C (2013) A reference architecture for organizing the internal structure of metadata-based frameworks. J Syst Softw 86(5):1239–1256

    Article  Google Scholar 

  • Guerra E, Buarque E, Fernandes C, Silveira F (2013b) A flexible model for crosscutting metadata-based frameworks. In: International conference on computational science and its applications, Springer, pp 391–407

  • Guerra E, Lima P, Choma J, Nardes M, Silva T, Lanza M, Meirelles P (2020) A metadata handling API for framework development: a comparative study. In: Proceedings of the 34th Brazilian symposium on software engineering, Association for Computing Machinery, New York, USA, SBES’20, pp 499–508. https://doi.org/10.1145/3422392.3422428

  • Guerra EM, Silveira FF, Fernandes CT (2009) Questioning traditional metrics for applications which uses metadata-based frameworks. In: Proceedings of the 3rd workshop on assessment of contemporary modularization techniques (acom’09), October, vol 26, pp 35–39

  • Guerra EM, de Souza JT, Fernandes CT (2010c) A pattern language for metadata-based frameworks. In: Proceedings of the 16th conference on pattern languages of programs, ACM, New York, USA, PLoP’09, pp 3:1– 3:29. https://doi.org/10.1145/1943226.1943230

  • Gunawardena S, Tempero E, Blincoe K (2023) Concerns identified in code review: A fine-grained, faceted classification. Information and Software Technology 153:107054. https://doi.org/10.1016/j.infsof.2022.107054, https://www.sciencedirect.com/science/article/pii/S0950584922001653

  • Hansen ME, Goldstone RL, Lumsdaine A (2013) What makes code hard to understand?. arXiv:1304.5257

  • Lawrie D, Morrell C, Feild H, Binkley D (2006) What’s in a name? a study of identifiers. In: 14th IEEE international conference on program comprehension (ICPC’06), IEEE, pp 3–12

  • Lima P, Guerra E, Meirelles P, Kanashiro L, Silva H, Silveira F (2018) A metrics suite for code annotation assessment. J Syst Softw 137:163–183

    Article  Google Scholar 

  • Lima P, Guerra E, Meirelles P (2020) Annotation sniffer: a tool to extract code annotations metrics. J Open Source Softw 5(47):1960. https://doi.org/10.21105/joss.01960

  • Lima P, Melegati J, Gomes E, Pereira NS, Guerra E, Meirelles P (2023) CADV: a software visualization approach for code annotations distribution. Information and Software Technology, pp 107089. https://doi.org/10.1016/j.infsof.2022.107089, https://www.sciencedirect.com/science/article/pii/S0950584922001987

  • Lucas W, Bonifácio R, Canedo ED, Marcílio D, Lima F (2019) Does the introduction of lambda expressions improve the comprehension of Java programs? In: Proceedings of the XXXIII Brazilian symposium on software engineering, pp 187–196

  • McHugh ML (2012) Interrater reliability: the kappa statistic. Biochemia Medica 22(3):276–282

    Article  MathSciNet  Google Scholar 

  • Pantiuchina J, Lanza M, Bavota G (2018) Improving code: The (mis) perception of quality metrics. In: 2018 IEEE international conference on software maintenance and evolution (ICSME), IEEE, pp 80–91

  • Piantadosi V, Fierro F, Scalabrino S, Serebrenik A, Oliveto R (2020) How does code readability change during software evolution? Empir Softw Eng 25:5374–5412

    Article  Google Scholar 

  • Posnett D, Hindle A, Devanbu P (2011) A simpler model of software readability. In: Proceedings of the 8th working conference on mining software repositories, Association for Computing Machinery, New York, USA, MSR’11, pp 73–82. https://doi.org/10.1145/1985441.1985454

  • Prana GAA, Ford D, Rastogi A, Lo D, Purandare R, Nagappan N (2021) Including everyone, everywhere: understanding opportunities and challenges of geographic gender-inclusion in OSS. IEEE Transactions on Software Engineering

  • Quinonez J, Tschantz M, Ernst M (2008) Inference of reference immutability. ECOOP 2008-Object-Oriented Programming pp 616–641. http://www.springerlink.com/index/6M5U5M330T81763T.pdf

  • Raymond DR (1991) Reading source code. In: Proceedings of the 1991 Conference of the centre for advanced studies on collaborative research, IBM Press, CASCON’91, pp 3–16

  • Rugaber S (2000) The use of domain knowledge in program understanding. Ann Softw Eng 9:143–192. http://dblp.uni-trier.de/db/journals/ansoft/ansoft9.html#Rugaber00

  • Santos RM, Gerosa MA (2018) Impacts of coding practices on readability. In: Proceedings of the 26th conference on program comprehension, pp 277–285

  • Scalabrino S, Bavota G, Vendome C, Linares-Vásquez M, Poshyvanyk D, Oliveto R (2017) Automatically assessing code understandability: How far are we? In: 2017 32nd IEEE/ACM international conference on automated software engineering (ASE), IEEE, pp 417–427

  • Schröter I, Krüger J, Siegmund J, Leich T (2017) Comprehending studies on program comprehension. In: 2017 IEEE/ACM 25th international conference on program comprehension (ICPC), pp 308–311. https://doi.org/10.1109/ICPC.2017.9

  • Šmite D, Wohlin C, Galviņa Z, Prikladnicki R (2014) An empirically based terminology and taxonomy for global software engineering. Empir Softw Eng 19:105–153

    Article  Google Scholar 

  • Spencer D (2009) Card sorting: Designing usable categories. Rosenfeld Media

  • Stackoverflow (2009) Arguments against annotations. https://stackoverflow.com/questions/1675610/arguments-against-annotations

  • Steinmacher I, Conte T, Gerosa MA, Redmiles D (2015) Social barriers faced by newcomers placing their first contribution in open source software projects. In: Proceedings of the 18th ACM conference on Computer supported cooperative work & social computing, pp 1379–1392

  • Storey MA, Wong K, Müller H (2000) How do program understanding tools affect how programmers understand programs? Sci Comput Program 36(2):183–207. https://doi.org/10.1016/S0167-6423(99)00036-2

    Article  Google Scholar 

  • Strauss AL, Corbin JM (1998) Basics of qualitative research : techniques and procedures for developing grounded theory. Sage Pub, Thousand Oaks

    Google Scholar 

  • Tashtoush Y, Odat Z, Yatim M, Alsmadi I (2013) Impact of programming features on code readability. Int J Softw Eng Appl 7(6):441–458

    Google Scholar 

  • Teixeira R, Guerra E, Lima P, Meirelles P, Kon F (2018) Does it make sense to have application-specific code conventions as a complementary approach to code annotations? In: Proceedings of the 3rd ACM SIGPLAN international workshop on meta-programming techniques and reflection, pp 15–22

  • Trinkenreich B, Wiese I, Sarma A, Gerosa M, Steinmacher I (2022) Women’s participation in open source software: a survey of the literature. ACM Trans Softw Eng Methodol (TOSEM) 31(4):1–37

    Article  Google Scholar 

  • Usman M, Britto R, Börstler J, Mendes E (2017) Taxonomies in software engineering: a systematic mapping study and a revised taxonomy development method. Inf Softw Technol 85:43–59

    Article  Google Scholar 

  • Wang Y, Redmiles D (2019) Implicit gender biases in professional software development: an empirical study. in: 2019 IEEE/ACM 41st international conference on software engineering: software engineering in society (ICSE-SEIS), pp 1–10. https://doi.org/10.1109/ICSE-SEIS.2019.0000

  • Warski A (2017) The case against annotations. SoftwareMill Tech Blog: https://blog.softwaremill.com/the-case-against-annotations-4b2fb170ed67

  • Wheaton GR, Fleishman EA (1968) Development of a taxonomy of human performance: a review of classificatory systems relating to tasks and performance. Clearinghous

  • Wulff-Jensen A, Ruder K, Triantafyllou E, Bruni LE (2019) Gaze strategies can reveal the impact of source code features on the cognitive load of novice programmers. In: Ayaz H, Mazur L (eds) Advances in neuroergonomics and cognitive engineering. Springer International Publishing, Cham, pp 91–100

    Chapter  Google Scholar 

  • Yang HY, Tempero E, Melton H (2008) An empirical study into use of dependency injection in java. In: 19th Australian conference on software engineering (aswec 2008), IEEE, pp 239–247

  • Yu Z, Bai C, Seinturier L, Monperrus M (2019) Characterizing the usage, evolution and impact of java annotations in practice. IEEE Transactions on Software Engineering

Download references

Acknowledgements

We thank all the respondents who spent their time answering our survey. We expect the results to benefit the developers and API designers and inspire new research on this topic. This work is partially supported by FAPESP (grant #2019/12743-4), CNPq/MCTI/FNDCT (grant #408812/2021-4), MCTIC/CGI/FAPESP (grant #2021/06662-1), and NSF (grants 2236198, 2247929, and 2303042).

Author information

Authors and Affiliations

  1. Free University of Bozen-Bolzano, Bozen-Bolzano, BZ, Italy

    Eduardo Guerra

  2. University of São Paulo, São Paulo, SP, Brazil

    Everaldo Gomes & Paulo Meirelles

  3. SONDA Brasil, São Paulo, SP, Brazil

    Jeferson Ferreira

  4. Federal Technological University of Paraná, Campo Mourão, PR, Brazil

    Igor Wiese

  5. Federal University of Itajubá, Itajubá, MG, Brazil

    Phyllipe Lima

  6. Northern Arizona University, Flagstaff, AZ, USA

    Marco Gerosa

Authors
  1. Eduardo Guerra
    View author publications

    You can also search for this author in PubMed Google Scholar

  2. Everaldo Gomes
    View author publications

    You can also search for this author in PubMed Google Scholar

  3. Jeferson Ferreira
    View author publications

    You can also search for this author in PubMed Google Scholar

  4. Igor Wiese
    View author publications

    You can also search for this author in PubMed Google Scholar

  5. Phyllipe Lima
    View author publications

    You can also search for this author in PubMed Google Scholar

  6. Marco Gerosa
    View author publications

    You can also search for this author in PubMed Google Scholar

  7. Paulo Meirelles
    View author publications

    You can also search for this author in PubMed Google Scholar

Corresponding author

Correspondence to Paulo Meirelles.

Ethics declarations

Conflict of Interest

The authors declared that they have no conflict of interest.

Additional information

Communicated by: David Lo.

Publisher's Note

Springer Nature remains neutral with regard to jurisdictional claims in published maps and institutional affiliations.

Rights and permissions

Springer Nature or its licensor (e.g. a society or other partner) holds exclusive rights to this article under a publishing agreement with the author(s) or other rightsholder(s); author self-archiving of the accepted manuscript version of this article is solely governed by the terms of such publishing agreement and applicable law.

Reprints and permissions

About this article

Check for updates. Verify currency and authenticity via CrossMark

Cite this article

Guerra, E., Gomes, E., Ferreira, J. et al. How do annotations affect Java code readability?. Empir Software Eng 29, 62 (2024). https://doi.org/10.1007/s10664-024-10460-w

Download citation

  • Accepted:

  • Published:

  • DOI: https://doi.org/10.1007/s10664-024-10460-w

Keywords

Search

Navigation