Code Comments

Code is typically written once but read by many. Current or future team members will read the code. In an open source project, many more folks including end users may read the code. Therefore, code readability is important. Sometimes when the code alone doesn't provide context or clarify intent, the developer may write extra descriptions. These descriptions are called code comments.

Code comments enhance readability. They facilitate code reviews, refactoring, and maintenance. Moreover, code comments are ignored by compilers and interpreters when producing the final executable. Thus, they incur no runtime performance overhead. However, too many or unnecessary comments can reduce readability.

All modern languages support code comments. Different languages have different syntaxes. Comments can be single-line or multi-line.

Discussion

  • What are the purposes for which code comments make sense?
    An example use of different types of comments in Java code. Source: Devopedia 2021.
    An example use of different types of comments in Java code. Source: Devopedia 2021.

    Code comments are used for various purposes:

    • Description: Used for describing the logic behind the code, not the code itself. Used for describing the algorithm or explaining why it was chosen. Even flowcharts in ASCII could be included.
    • Licensing: Licensing or copyright information are written as comments.
    • Metadata: Could include author and date of the first version, name and contact of current maintainer. Could include external references to provide context, such as, a published paper or a StackOverflow answer.
    • Pending Work: Comments tagged with FIXME or TODO indicate pending work. Editors/IDEs often recognize them.
    • Debugging: Developers comment out redundant code or code causing problems. These comments are ideally deleted once the problem is found.
    • Directives: Directives meant for editors and interpreters. For example, UNIX scripts use #! to know what interpreter must be used. Python uses # -*- coding: UTF-8 -*- to inform the encoding used for the source file.
    • Documentation: For documenting interfaces and to assist editors/IDEs. Tools exist to automatically create documentation from these comments. Some developers treat these as documentation, not comments.
  • What are some anti-patterns when writing code comments?
    Avoid excessive comments, instead summarize a block of code. Source: Adapted from Avram 2010.
    Avoid excessive comments, instead summarize a block of code. Source: Adapted from Avram 2010.

    Writing lots of comments explaining every single detail of what the code does is an anti-pattern. Too many comments clutter the source file and reduce readability. Moreover, such comments are also hard to maintain as the code evolves.

    Using comments to keep a historical record of how the code has evolved is an anti-pattern. This is best done by your version control system. Old code that's no longer used should not be commented. It's cleaner to delete the code. If required, we can always get it from the version control system.

    Magic comments are those that give editors and interpreters directives. These may be important for the correct working of the software. Mixing such comments with regular comments can be problematic. Someone may delete the magic comments by mistake.

  • Aren't comments an indication of bad code?

    Some developers believe that comments are not necessary if the code is clean. Comments don't fix bad code. It's been said that,

    Don't document bad code – rewrite it.

    From this perspective, there are ways to refactor bad code and get rid of unnecessary comments:

    • Naming: A variable i could be renamed to numGoals, which clarifies intention. Do this for variables, methods and classes.
    • Structure: If a code fragment can't be understood without comments, try to change the code structure. Design patterns help in this regard.
    • Sub-expressions: Where there's a complex expression, split it into multiple sub-expressions.
    • New Method: A comment that explains a block of code can be removed by extracting that code into its own method. The method's name should clarify intent.
    • Assertion: A variable may be expected to obey some constraint. Don't state this in a comment. Instead, use an assertion.

    When all the above are employed and code is refactored, only a few comments may remain. Mostly likely, these explain why the code is written in a certain way or describe complex algorithms that couldn't be simplified.

  • Could you share some tips for writing code comments?
    Comments in a visual programming language such as Scratch. Source: Prozzi 2016.
    Comments in a visual programming language such as Scratch. Source: Prozzi 2016.

    Avoid commenting what's already obvious in the code. Comments should explain at a higher level of abstraction. In other words, "why" comments are good, "how" comments are bad.

    Organize code into blocks, each block performing a single task. A comment could precede each block. This makes it easier for others to follow the flow at a high level. In fact, some developers write these comments first before writing the code.

    Get to the point. Avoid jokes, poetry and verbosity. Be polite in your comments. Write comments in a consistent style. Write them for other developers, although some write them for non-programmers. If you write TODO comments, remember to take action on these later. Update comments when updating code.

    Some developers argue that multi-line nested comments are a bad idea. They can lead to run-away comments that create bugs.

    Take inspiration from guidelines defined by others. For example, Google Style Guides are available for many languages and most of these include guidelines for comments. There are also guidelines for documenting APIs.

  • What are some patterns for writing code comments?

    Experienced developers most likely know when and how to write good code comments. Chris Travers has attempted to formalize these practices by giving them names:

    • Documentation Comment Pattern: For documenting interfaces and not for explaining the code itself.
    • Section Heading Comment Pattern: Comments are used to separate sections of code, such as public vs private methods. Helpful to organize code and find things quickly later.
    • Footnote Comment Pattern: Comments that describe why a particular approach was adopted. Short and informative. Generally used when such information can't be deduced from the code.
    • Warning Comment Pattern: Comments that warn developers of some special needs, such as calling a function as a superuser. Warnings may be about security or design flaws. Comments may include TODO or FIXME annotations.
    • Signed Comment Pattern: Useful in a team. Comments are accompanied by initials of the developer. Makes it easy to know who to approach for discussions.
    • Woven Code Pattern: Code and documentation are go together. Document first and then code to that documentation.
  • Which are the syntax types for code comments?

    Comment syntaxes vary across languages but basically there are two types:

    • Inline Comment: Used for a single-line comment, marked by a start comment token till the end of the line.
    • Block Comment: Used for a multi-line comment, marked by a pair of start-end comment tokens. In some languages, block comments can be nested, that is, a block comment within another block comment is permitted.

    A language may support one or both types of syntaxes. Some languages such as ALGOL, Mathematica, OCaml, Simula, and Smalltalk don't have a single-line comment syntax but the token pair for block comments may be used within the same line. Some languages such as R, Python, FORTRAN, Erlang and Visual Basic don't have block comments. Though Python has """ … """, these are meant for documentation, not comments.

    PHP is an example that supports multiple syntaxes for inline comments (# and //).

  • What's the syntax for adding comments to source code?

    Without being exhaustive, we list some start tokens used for inline comments:

    • #: UNIX/Linux shells, Cobra, Perl, Python, Ruby, Seed7, Windows PowerShell, PHP, R, Make, Maple, Elixir, Nim
    • //: ActionScript, C, C++, C#, D, F#, Go, Java, JavaScript, Kotlin, Objective-C, PHP, Rust, Scala, SASS, Swift, Xojo
    • --: Euphoria, Haskell, SQL, Ada, AppleScript, Eiffel, Lua, VHDL, SGML, PureScript
    • %: TeX, Prolog, MATLAB, Erlang, S-Lang, Visual Prolog
    • ;: Assembly x86, Lisp, Common Lisp, Clojure, Scheme
    • REM: BASIC, Batch files

    We list some start-end token pairs for block comments:

    • /* … */: ActionScript, C, C++, C#, D, Go, Java, JavaScript, Kotlin, Objective-C, PHP, PL/I, Prolog, Rexx, Rust, Scala, SAS, SASS, SQL, Swift, Visual Prolog, CSS
    • (* … *): Delphi, ML, Mathematica, Object Pascal, Pascal, Seed7, Applescript, OCaml, Standard ML, Maple, Newspeak, F#
    • #| … |#: Lisp, Scheme, Racket
    • =begin … =end: Ruby
  • Can data have comments attached to them?
    Trailing comments (in blue) in a YAML file. Source: Johnson 2020.
    Trailing comments (in blue) in a YAML file. Source: Johnson 2020.

    Indeed, data can have comments too. Like code comments, these can be descriptions, metadata, references, etc. For example, static web content is served commonly in HTML. HTML (and XML) documents can have comments within <!-- … --> that are not displayed by web browsers.

    It's common for computer systems to use configuration files. Typical formats are Microsoft Windows INI, XML, JSON and YAML. Except for JSON, all others allow for comments. Although JSON doesn't support comments by syntax, developers have found a way to add comments from a semantic standpoint by following certain naming conventions. For example, "_comment1": "this is my comment" is a comment although JSON parsers will treat is as data. The reason JSON doesn't have a comment syntax is that developers were adding parsing directives in them, thereby making it less interoperable.

    Comments in configuration files probably make sense just as comments in code. In a quote that's attributed to James Gosling, it's been said that,

    Every configuration file becomes a programming language, so you might as well think that way.

Milestones

1957

Designed at IBM, FORTRAN is released as a programming language along with a compiler. FORTRAN allows comments, thereby making the code accessible to non-programmers. A comment is a full-line comment marked by letter C at position 1 till the end of the line. COBOL and BASIC that follow soon after also support comments from a fixed position. The use of fixed position simplified compiler design. We should note that since the early 1950s assemblers have supported comments starting at any position, including trailing comments.

1960

ALGOL is defined by a committee as a "second-generation" language. It supports block comments. Pascal takes inspiration from ALGOL and is released in 1970. It also supports block comments.

1970

Through the 1970s, structured programming becomes more popular. The same can be said of object-oriented programming in the 1980s. Programs evolve to higher levels of abstraction. Programs become more organized. Computer systems have more memory and so variable names could be longer and more descriptive. Hungarian notation is less favoured. These developments imply a lesser need to write comments.

1981

In one of the earliest experiments, Woodfield et al. find that code comments improve readability. Tenny (1985) shows that comments improve the understanding of the Banker's Algorithm. Further experiments through the 1980s and early 1990s confirm these findings and highlight the importance of code comments in maintaining large software projects.

Oct
2007

Fluri et al. report results of a study on how code and its comments evolve. Based on three open source projects, they find that new code is barely accompanied by comments. Class and method declarations are commented more often than method calls. About 97% of comment changes are done in the same version as the code changes. Their research method associates code with comments based on proximity and a token-based string similarity measure.

2010

Since writing comments is extra work for developers, it's common to encounter code that's inadequately commented. During the period 2010-2014, tools emerge to automatically generate code comments. These use techniques from Information Retrieval (IR). From the mid-2010s, neural networks are more often employed for this problem.

2011

Haouari et al. present one of the first taxonomies for code comments. They identify four high-level categories.

2013
Positive and negative impacts of comments by categories on activities. Source: Steidl et al. 2013, fig. 1.
Positive and negative impacts of comments by categories on activities. Source: Steidl et al. 2013, fig. 1.

Steidl et al. identify seven high-level categories of comments. Their main aim is to understand developers' commenting habits. They find that commenting out code has negative impact on code readability. Section comments such as // ---- Getter and Setter Methods --- improve readability. Method comments help callers understand the system design and how to call those methods.

Feb
2019

Code comments sometimes include links to licenses, software homepages, and specifications. Hata et al. analyze 9.6 million links and find that about 10% are outdated. The point is that links in comments are fragile and need regular maintenance.

Apr
2019
A taxonomy of Java code comments. Source: Pascarella et al. 2019, fig. 1.
A taxonomy of Java code comments. Source: Pascarella et al. 2019, fig. 1.

Pascarella et al. manually classify 40,000 lines of code comments from 14 open source Java projects. Their goal is to empirically determine the types of comments developers are writing. In the process, they develop a taxonomy of code comments. They also develop machine learning features and algorithms to automate the classification.

References

  1. Aguilar, José M. 2008. "13 Tips to Comment Your Code." Translated to English by Timm Martin, DevTopics, March 14. Accessed 2021-09-29.
  2. Avram, Abel. 2010. "To Comment or Not to Comment." InfoQ, March 3. Accessed 2021-09-29.
  3. Britannica. 2021. "FORTRAN, COBOL, and ALGOL." UNIVAC, Computer, Britannica. Accessed 2021-09-30.
  4. Cronin, Mike. 2019. "What Makes a Good Code Comment?" ITNEXT, on Medium, October 13. Accessed 2021-09-29.
  5. Dietrich, Erik. 2017a. "Code Documentation and Code Comments Aren't the Same Thing." Blog, SubMain Software, September 26. Accessed 2021-09-29.
  6. Dietrich, Erik. 2017b. "A Field Guide to Code Comments." Blog, SubMain Software, October 3. Accessed 2021-09-29.
  7. Drasner, Sarah. 2020. "The Art of Code Comments." JSConf Hawaii, JSConf on YouTube, March 27. Accessed 2021-09-29.
  8. Easter, Michael. 2008. "A fascinating quote attributed to James Gosling." Blog, Code To Joy, September 24. Accessed 2021-09-29.
  9. Erik. 2018. "YAML Tutorial: Everything You Need to Get Started in Minutes." Blog, CloudBees, December 11. Accessed 2021-09-29.
  10. Fluri, Beat, Michael Würsch, and Gall, Harald C. 2007. "Do code and comments co-evolve? On the relation between source code and comment changes." 14th Working Conference on Reverse Engineering (WCRE 2007), October 28-31. doi: 10.1109/WCRE.2007.21. Accessed 2021-09-29.
  11. Google Developers. 2020. "API reference code comments." Google Developer Documentation Style Guide, December 30. Accessed 2021-09-29.
  12. Haddad, Amy. 2020. "JSON Comment Example — How to Comment in JSON Files." freeCodeCamp, April 26. Accessed 2021-09-29.
  13. Hata, Hideaki, Christoph Treude, Raula Gaikovina Kula, and Takashi Ishio. 2019. "9.6 Million Links in Source Code Comments: Purpose, Evolution, and Decay." arXiv, v2, February 15. Accessed 2021-09-29.
  14. JetBrains. 2021. "TODO comments." Help, IntelliJ IDEA, v2021.2, June 15. Accessed 2021-09-29.
  15. Johnson, Tom. 2020. "Working in YAML (OpenAPI tutorial)." Step-by-step OpenAPI tutorial, I'd Rather Be Writing, September 7. Accessed 2021-09-29.
  16. Khare, Mohit. 2021. "Example of Adding Comments in 15 Programming Languages." Geekflare, February 25. Accessed 2021-09-29.
  17. Pascarella, Luca, Magiel Bruntink, and Alberto Bacchelli. 2019. "Classifying code comments in Java software systems." Empirical Software Engineering, vol. 24, pp. 1499-1537, April 26. Accessed 2021-09-29.
  18. PHP. 2021. "Comments." Language Reference, PHP Manual. Accessed 2021-09-29.
  19. Prozzi, Jonathan. 2016. "Commenting Code in Scratch." DHF Blueprint, April 11. Accessed 2021-09-29.
  20. Python Docs. 2021. "configparser — Configuration file parser." Documentation, Python 3.9.7, September 21. Accessed 2021-09-29.
  21. Refactoring Guru. 2020. "Comments." Code Smells, Refactoring Guru, January 1. Accessed 2021-09-29.
  22. RubyCademy. 2019. "Magic Comments in Ruby." RubyCademy, on Medium, August 13. Accessed 2021-09-30.
  23. Song, Xiaotao, Hailong Sun, Xu Wang, and Jiafei Yan. 2019. "A Survey of Automatic Generation of Source Code Comments: Algorithms and Techniques." IEEE Access, vol. 7, pp. 111411-111428, July 29. Accessed 2021-09-30.
  24. Steidl, Daniela, Benjamin Hummel, and Elmar Juergens. 2013. "Quality Analysis of Source Code Comments." 21st International Conference on Program Comprehension (ICPC), May 20-21. doi: 10.1109/ICPC.2013.6613836. Accessed 2021-09-29.
  25. Travers, Chris. 2012. "Patterns and Anti-Patterns in Code Comments." Blog, Perspectives on LedgerSMB, August 2. Accessed 2021-09-29.
  26. UMKC. 2021. "History of Pascal." CS 441, University of Missouri-Kansas City. Accessed 2021-09-30.
  27. Van Tassel, Dennie. 2004. "Comments in programming languages." February 12. Accessed 2021-09-29.
  28. Wikipedia. 2021a. "Comparison of programming languages (syntax)." Wikipedia, September 19. Accessed 2021-09-29.
  29. Wikipedia. 2021b. "Comment (computer programming)." Wikipedia, September 24. Accessed 2021-09-29.
  30. Wikipedia. 2021c. "Structured programming." Wikipedia, September 21. Accessed 2021-09-30.
  31. Wood, Adam. 2019. "The HTML Comment Tag: Here’s How To Use It In Your Code." HTML.com, November 22. Accessed 2021-09-29.

Further Reading

  1. Drasner, Sarah. 2020. "The Art of Code Comments." JSConf Hawaii, JSConf on YouTube, March 27. Accessed 2021-09-29.
  2. Travers, Chris. 2012. "Patterns and Anti-Patterns in Code Comments." Blog, Perspectives on LedgerSMB, August 2. Accessed 2021-09-29.
  3. Aguilar, José M. 2008. "13 Tips to Comment Your Code." Translated to English by Timm Martin, DevTopics, March 14. Accessed 2021-09-29.
  4. Steidl, Daniela, Benjamin Hummel, and Elmar Juergens. 2013. "Quality Analysis of Source Code Comments." 21st International Conference on Program Comprehension (ICPC), May 20-21. doi: 10.1109/ICPC.2013.6613836. Accessed 2021-09-29.
  5. Song, Xiaotao, Hailong Sun, Xu Wang, and Jiafei Yan. 2019. "A Survey of Automatic Generation of Source Code Comments: Algorithms and Techniques." IEEE Access, vol. 7, pp. 111411-111428, July 29. Accessed 2021-09-30.

Article Stats

Author-wise Stats for Article Edits

Author
No. of Edits
No. of Chats
DevCoins
3
0
1378
2064
Words
0
Likes
11
Hits

Cite As

Devopedia. 2021. "Code Comments." Version 3, October 1. Accessed 2021-10-01. https://devopedia.org/code-comments
Contributed by
1 author


Last updated on
2021-10-01 05:52:24
  • Docstring
  • API Documentation
  • Automatic Code Comment Generation
  • Coding Guidelines
  • Clean Code
  • Code Refactoring