International Journal of Computing and Corporate Research ISSN (Online) : 2249-054X Volume 3 Issue 4 July 2013 Manuscript ID : 2249054XV3I4072013-04

AN EMPIRICAL SURVEY ON USEFULNESS OF COMMENTS IN SOFTWARE PROGRAMMING LANGUAGES

Manjot Singh Ahuja, Surender Dhaiya, Neha Sadana {manjot.ahuja, surendahiya, sadananeha25}@gmail.com Computer Science and Engineering Department Shivalik Institute of Engineering and Technology, Aliyaspur (Ambala)

ABSTRACT

Each programming language and script has comments to make it further reusable. This its own coding conventions. There are documentation will take form of external, numerous general points that can be internal documentation, comments, and followed to ensure that the code is well readme files. organised so that it can be easily understood for maintenance and External documentation - Explains the reengineering. These guidelines are helpful methods of software development. in formalising code so that interpretation, reuse, maintenance, re-engineering and Internal documentation - Explains the way reverse-engineering of code become to implement the code. easier. The source code comment gives high-level advice for software developer. Comments - Comments must be added to This paper presents an overview of the code to explain the implementation conventions and importance of comments details of the source code. It is mandatory in source code during development as well to avoid adding of obvious or lengthy as in maintenance. information. Prior to the project development, we should agree on how Keywords - Code Quality, Source Code, frequent comments should be and their Source Code Comments, Source Code location, format and length in the file. Comments Quality These conventions may need to be agreed on for block, single-line and end-of-line comments. 1 Introduction Readme file - Every package should have Source code documentation is the text the readme file unfolding the purpose and which accompanies computer software and functionality of the software and either explains how it operates or how to information on exterior dependencies. use it. Code comments are used to embed programmer-readable remarks in the source code of a program. These 2 Taxonomy of the Comments annotations are ignorable to compilers and 2.1 Prefacing interpreters. The source code comments are typically additional artifacts with the This is the practice of starting each rationale of the ease to comprehension of programming with a block comment that source code. The syntax and rules for briefly describes it. Ideally, the preface comments diverge and are typically should not be overly long, and it should defined in a programming language summarize the purpose of its programming specification. While developing software it unit. The advantages of prefacing are is important that you include the clear twofold, it is a useful tool for any documentation as well as the code maintainers who may need to understand International Journal of Computing and Corporate Research ISSN (Online) : 2249-054X Volume 3 Issue 4 July 2013 Manuscript ID : 2249054XV3I4072013-04 the code in the future; but it can also be Python, Ruby, Windows PowerShell, PHP, beneficial for the developer writing the Maple), % (TeX, Prolog, MATLAB, code, helping to concretize the purposes in Erlang, S-Lang, Visual Prolog), etc.. his mind. In addition, best practices have always stipulated that programming units Block comments - Block comments are should be single-purpose, and in writing generally those that use a delimiter to the prefacing comments, the developer indicate the beginning of a comment, and will catch himself if he is about to flout another delimiter to indicate the end of a this rule. comment. In this context, whitespace and newline characters are not counted as 2.2 Comment-Driven Development delimiters.

This is a programming methodology that Examples: /* */ (C, C++, C#, D, Go, Java, encourages the developers to start out JavaScript, Objective-C, PHP, Visual complex projects by building a wireframe Prolog, CSS), { } (Object Pascal (Delphi), of their procedures using little more than Pascal), etc. comments and basic pseudo code to describe each step of the algorithm. CDD 4 Approaches and Protocols for help developers to encounter and work out Comments problems before they write a line of actual code; it also has the advantage of helping Commenting styles should be governed by clearly delineate the routes between the a company’s development guidelines and, high-level problem and the many small- even within these guidelines, there is often picture fractals it is composed of. The enough wriggle room for individual style comments created using CDD may survive and subjectivity. The following are few the process of actual coding and rules and practices that should be followed development as line comments throughout when commenting code. the programming unit; however, it sometimes make sense to delete them after To include a preface: It need not be a long their purpose has been served. essay, in fact, it should not be long. However, it is important to include one. 3 Comments Style and Format Apart from focusing the developer’s mind around the task and assisting any • Style (inline/block) maintainer that may come along in the • Parse rules (ignored/interpolated/stored future, prefaces can serve an important, in memory) additional function. Some languages, most • Recursivety (nestable/non-nestable) notably Java, but also PHP include API- • Uses (docstrings/throwaway generating functionality: Javadoc and comments/other) PHPdoc, respectively. PL/SQL presents us with no such nicety, but if all Inline Comments - Inline comments are programming units contain prefacing generally those that use a newline comment blocks, then we can write of our character to indicate the end of a comment, own quite easily. and an arbitrary delimiter or sequence of tokens to indicate the beginning of a Include a revision history : Anyone comment. maintaining your code in the future will thank you for including a revision history. Examples: // (C++, C#, D, Go, Java, The identity of the developer who has JavaScript, Object Pascal (Delphi), made a particular change is not so Objective-C, PHP), # (bash, Cobra, Perl, important, however, it may one day be International Journal of Computing and Corporate Research ISSN (Online) : 2249-054X Volume 3 Issue 4 July 2013 Manuscript ID : 2249054XV3I4072013-04 vital to know when a change was made would make the code very readable and why. and will not need many comments. • Do not write comments if the code is Use line comments: A good rule is to use a easily understandable without single line comment at the start of each comment. The drawback of having lot logical block describing what it does. If, in of comments is, if you change the code the future, someone needs to maintain your and forget to change the comment, it code, they should not need to read every will lead to more confusion. line of code to pinpoint the section they • Fewer lines of comments will make the intend to edit; in fact, they should be able code more elegant. But if the code is to navigate your whole procedure or not clean/readable and there are less package without reading a single line of comments, that is worse. code outside the actual section they are • If you have to use some complex or looking for. A good developer, unlike a weird logic for any reason, document it good novelist, is one whose best work is very well with sufficient comments. never read in full. • If you initialize a numeric variable to a special number other than 0, -1 etc, Never depend on your memory: Writing document the reason for choosing that something complicated? Comment it. value. Code, algorithms and assumptions that are perfectly clear at the time of writing, can 5 Literature Survey quickly fester in a morass of spaghetti code with time. In early 1980s Donald Knuth suggested literate programming [5], in order to Comment while maintaining code: If you combine the process of software are forced to wade through old poorly- documentation with software commented or uncommented code that you programming. Comments are ignored by or another developer has written, do not compiler, so, in order to differentiate leave it as you found it. Comment it. source code and documentation, a specific While you may not be responsible for the documentation or programming syntax has way you find code, you are responsible for to be used. Programmers typically lack the the way you leave it. appropriate tools and processes to create and maintain documentation, it has been Keep it simple: Comments should be widely considered as an unfavorable and easily readable. Keep them as short as labor-intensive task within software possible, and as plain as possible. Unless projects [6]. absolutely necessary, do not include any For generating comments in JAVA, code in your comments. Javadoc [7] is an automated tool that generates API documentation in HTML Good and meaningful comments make using Java source code and source code code more maintainable. However, comments. Javadoc comments added to • Do not write comments for every line source code are distinguishable from of code and every variable declared. normal comments by a special comment • Use // or /// for comments. Avoid using syntax (/**). /* … */ In [8], Khamis et al. provided an analysis tool called JavadocMiner for analyzing the • Write comments wherever required. quality of inline documentation. Thereby, But good readable code will require the authors mainly focused on inline- very less comments. If all variables documentation in the form of Javadoc and method names are meaningful, that comments. By using a set of heuristics, International Journal of Computing and Corporate Research ISSN (Online) : 2249-054X Volume 3 Issue 4 July 2013 Manuscript ID : 2249054XV3I4072013-04 they aimed to evaluate both the quality of In addition to [10], Ying et al [11] also the language and the consistency between investigated the role of task comments. source code and its comments. The quality The authors interpreted the intention of of the language was measured with task comments, resulting in a detailed heuristics such as counting the number of categorization of task comments such as tokens, nouns, and verbs, calculating the bookmarks on past tasks, current tasks, average number of words, or counting the future tasks, pointers to change requests, number of abbreviations. With heuristics or tasks used for communication. including the Fog index or the Flesch However, there was no automatic or semi- reading ease level, the authors targeted the automatic assessment of task comment readability of comments. For detecting quality. inconsistencies between code and Fluri et al. [12] concluded that code and comments, this approach computes the comments are not necessarily get updated ratio of identifiers with Javadoc comments and evolve at the same time. Therefore, the to the total number of identifiers and authors investigated how code and checked whether all aspects of a method comments evolve. They used a mapping such as parameter or return type are between code and comments to observe documented. The heuristics are grouped their co-evolution over multiple versions into two categories, Internal (Natural of the system. The authors conducted a Language quality only) and code/comment case study on three different Java projects. consistency. The case study, in contrast, revealed that Lehman and Belady in their paper [9] comment change is triggered by source surveyed that with millions of lines of code change; about 97% are done in the code written every day, the importance of same revision as the source code change. good documentation cannot be overstated. Furthermore, approximately 70% of Well-documented software components comments are mapped to one of the are easily comprehensible and therefore, following seven types of source code maintainable and reusable. This becomes entities: attributes, class and method especially important in large software declarations, control structures, loops, systems. method calls, and variable declarations. Storey et al [10] focused on study to The authors also evaluated the ratio explore the role embedded task between comments and source code over annotations play in source code. They time to give a trend analysis whether gathered data from a survey among developers increase or decrease their effort software developers, from code analysis of on code commenting. However, the results open source projects, and from personal differed greatly among the three test cases interviews. They found that task comments such that no unique answer can be given. are frequently used in software In particular, the authors did not development with the majority of differentiated between different types of comments containing TODO tags. TODO comments, e. g., lines of commented out comments mainly serve the purpose of code were also counted in the ratio documenting small tasks when opening a between comments and source code. new bug report. However, there is the Sundbakken [13] assessed the comment potential risk that developers never revisit density of maintenance phase code task comments. Based on this analysis, the contributions to components of four open authors suggested several implications for source projects. He observes that tool designer, such as providing altering consistent commenting correlates highly mechanism for task views, supporting with maintainability of components. The meta data within task comments, or measured comment density ranged from introducing ad-hoc task clean-up wizards. 0.09% for poorly maintainable International Journal of Computing and Corporate Research ISSN (Online) : 2249-054X Volume 3 Issue 4 July 2013 Manuscript ID : 2249054XV3I4072013-04 components to 1.22% for highly Conclusion maintainable components. In contrast to [13], in a study on the comment density of Technical experts documented the varying a closed-source compiler project in its viewpoints on whether and when maintenance phase, Siy and Votta found a comments are appropriate in source code. consistent comment density of around 50% Some commentators avow that source [14]. In another study of 100 Java open code should be written with few source classes, Elish and Offutt found an comments, on the basis that the source average comment density of 15.2% with a code should be self-explanatory. Others standard deviation of 12.2% [15]. Fluri et suggested that code should be extensively al. presented an approach for assessing the commented. These views assert that comment density of software projects and excessive comments are neither beneficial demonstrated the approach using three nor harmful, what matters is that they selected open source projects [12]. They should be correct and kept in sync with the also observed that new code is barely source code, and omitted if they are commented, implying that comment superfluous, excessive, difficult to density decreases over time. maintain or otherwise unhelpful. It is very Oliver and Dirk in their paper [16] important to specify the comments in the concluded that commenting source code is software source code very carefully so that a consistent practice of active open source it will be understandable, readable as well projects. It has led to an average comment as modifiable. It also reduces maintenance density of about 19%. This density is cost, helps in maintainability, maintained by dedicated commenting understandability, software reusability, re- activities as well as in regular on-going engineering and in reverse-engineering. programming activities. Also, they have This becomes especially important in large found that the average comment density is software systems. As we have seen in the independent of team size and project size, earlier section that there are many suggesting that as teams and projects get categories of documentation and larger, successful open source projects comments. Some suggested ideas for in- maintain their commenting discipline. line comments, some for block-comments, However, the average comment density is some for specific language, and some not independent of a project’s age but suggested where comments should be rather declines with an aging project. That added and where not to add, some talked decline is statistically significant; however, about comment density. it is rather small and thus has limited practical implications. Since in-line comments come in contact with various stakeholders of a software 6 Limitation project, it needs to effectively communicate the purpose of a given Source code comments are essential for implementation to the reader. So research understandability of code and less work demands quality of in-line comments and has been done on the qualitative analysis we are trying to achieve the same by of comments. If we put aside quality of taking other parameters in consideration. source code comments, nearly no work has And our work will not be limited to any been done related to understandability of specific programming language; we will source code with respect to comments. try to implement it on variety of And works done by authors till now are programming languages and will study limited to any specific language, no model how quality of source code comments has been proposed that will get fit to many effect understandability. programming languages. International Journal of Computing and Corporate Research ISSN (Online) : 2249-054X Volume 3 Issue 4 July 2013 Manuscript ID : 2249054XV3I4072013-04

References [10] Margaret-Anne Storey, Jody Ryall, R. Ian Bull, Del Myers, and Janice [1] Penny Grubb, Armstrong Takang Singer. TODO or To Bug: Exploring (2003). Software Maintenance: How Task Annotations Play a Role in Concepts and Practice. World the Work Practices of Software Scientific. pp. 7, 120–121. ISBN 981- Developers. In Proceedings of the 30th 238-426-X. International Conference on Software [2] Vermeulen, Al (2000). The Elements Engineering, ICSE '08, pages 251{260. of Java Style. Cambridge University ACM, 2008. Press. ISBN 0-521-77768-2. [11] Annie T. T. Ying, James L. Wright, [3] "Using the right comment in Java". and Steven Abrams. Source code that Retrieved 2007-07-24. talks: an exploration of Eclipse task [4] W. R., Dietrich (2003). Applied comments and their implication to Pattern Recognition: Algorithms and repository mining. In Proceedings of Implementation in C++. Springer. the 2005 International Workshop on ISBN 3-528-35558-1. offers Mining Software Repositories, MSR viewpoints on proper use of comments '05, pages 1-5. ACM, 2005. in source code. p. 66. [12] Beat Fluri, Michael Wursch, and [5] Knuth, D.E.: Literate Programming. Harall Gall. “Do Code and Comments The Computer Journal 27(2) (1984) Co-Evolve? On the Relation Between 97{111 Source Code and Comment Changes.” [6] Brooks, R.E.: Towards a Theory of the In Proceedings of the 14 th Working Comprehension of Computer Conference on Reverse Engineering Programs. International Journal of (WCRE2007). Page 70-79. Man-Machine Studies 18(6) (1983) [13] Marius Sundbakken. Assessing the 543{554 Maintainability of C++ Source Code. [7] Kramer, D.: API documentation from M.S. Thesis,Washington State source code comments: a case study of University, 2001. Javadoc. In: SIGDOC '99: Proceedings [14] Harvey Siy, Lawrence Votta. of the 17th annual international “Does the Modern Code Inspection conference on Computer have Value?” In Proceedings of the documentation, New York, NY, USA, 17 th IEEE International Conference on ACM (1999) 147{153 Software Maintenance (ICSM 01). [8] Ninus Khamis, Rene Witte, and Jurgen IEEE Press, 2001. Page 281-290. Rilling. Automatic Quality Assessment [15] Mahmoud Elish, Jeff Offutt. “The of Source Code Comments: Adherence of Open Source Java the JavadocMiner. In Proceedings of Programmers to Standard Coding the Natural Language Processing and Practices.” In Proceedings of the 6th Information Systems, and 15th IASTED International Conference International Conference on Software Engineering and Applications of Natural Language to Applications. Page 193-198. Information Systems, NLDB '10, pages 68-79. Springer-Verlag, 2010. [16] http://www.cs.uoregon.edu/events/i cse2009/images/postPosters/The%20C [9] Lehman, M.M., Belady, L.A., eds.: omment%20Density%20of%20Open% Program evolution: processes of 20Source%20Software%20Code.pdf software change. Academic Press “The Comment Density of Open Professional, Inc., San Diego, CA, Source Software Code” USA (1985)