DOCSLIB.ORG

An Empirical Survey on Usefullness of Comments in Software Programming

Total Page：16

File Type：pdf, Size：1020Kb

Download full-text PDF Read full-text
An Empirical Survey on Usefullness of Comments in Software Programming 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.
Load more

Recommended publications
  • A First Course to Openfoam
    Basic Shell Scripting Slides from Wei Feinstein HPC User Services LSU HPC & LON [email protected] September 2018 Outline • Introduction to Linux Shell • Shell Scripting Basics • Variables/Special Characters • Arithmetic Operations • Arrays • Beyond Basic Shell Scripting – Flow Control – Functions • Advanced Text Processing Commands (grep, sed, awk) Basic Shell Scripting 2 Linux System Architecture Basic Shell Scripting 3 Linux Shell What is a Shell ▪ An application running on top of the kernel and provides a command line interface to the system ▪ Process user’s commands, gather input from user and execute programs ▪ Types of shell with varied features o sh o csh o ksh o bash o tcsh Basic Shell Scripting 4 Shell Comparison Software sh csh ksh bash tcsh Programming language y y y y y Shell variables y y y y y Command alias n y y y y Command history n y y y y Filename autocompletion n y* y* y y Command line editing n n y* y y Job control n y y y y *: not by default http://www.cis.rit.edu/class/simg211/unixintro/Shell.html Basic Shell Scripting 5 What can you do with a shell? ▪ Check the current shell ▪ echo $SHELL ▪ List available shells on the system ▪ cat /etc/shells ▪ Change to another shell ▪ csh ▪ Date ▪ date ▪ wget: get online files ▪ wget https://ftp.gnu.org/gnu/gcc/gcc-7.1.0/gcc-7.1.0.tar.gz ▪ Compile and run applications ▪ gcc hello.c –o hello ▪ ./hello ▪ What we need to learn today? o Automation of an entire script of commands! o Use the shell script to run jobs – Write job scripts Basic Shell Scripting 6 Shell Scripting ▪ Script: a program written for a software environment to automate execution of tasks ▪ A series of shell commands put together in a file ▪ When the script is executed, those commands will be executed one line at a time automatically ▪ Shell script is interpreted, not compiled.
    [Show full text]
  • Bash Guide for Beginners
    Bash Guide for Beginners Machtelt Garrels Garrels BVBA <tille wants no spam _at_ garrels dot be> Version 1.11 Last updated 20081227 Edition Bash Guide for Beginners Table of Contents Introduction.........................................................................................................................................................1 1. Why this guide?...................................................................................................................................1 2. Who should read this book?.................................................................................................................1 3. New versions, translations and availability.........................................................................................2 4. Revision History..................................................................................................................................2 5. Contributions.......................................................................................................................................3 6. Feedback..............................................................................................................................................3 7. Copyright information.........................................................................................................................3 8. What do you need?...............................................................................................................................4 9. Conventions used in this
    [Show full text]
  • Lecture 17 the Shell and Shell Scripting Simple Shell Scripts
    Lecture 17 The Shell and Shell Scripting In this lecture • The UNIX shell • Simple Shell Scripts • Shell variables • File System commands, IO commands, IO redirection • Command Line Arguments • Evaluating Expr in Shell • Predicates, operators for testing strings, ints and files • If-then-else in Shell • The for, while and do loop in Shell • Writing Shell scripts • Exercises In this course, we need to be familiar with the "UNIX shell". We use it, whether bash, csh, tcsh, zsh, or other variants, to start and stop processes, control the terminal, and to otherwise interact with the system. Many of you have heard of, or made use of "shell scripting", that is the process of providing instructions to shell in a simple, interpreted programming language . To see what shell we are working on, first SSH into unix.andrew.cmu.edu and type echo $SHELL ---- to see the working shell in SSH We will be writing our shell scripts for this particular shell (csh). The shell scripting language does not fit the classic definition of a useful language. It does not have many of the features such as portability, facilities for resource intensive tasks such as recursion or hashing or sorting. It does not have data structures like arrays and hash tables. It does not have facilities for direct access to hardware or good security features. But in many other ways the language of the shell is very powerful -- it has functions, conditionals, loops. It does not support strong data typing -- it is completely untyped (everything is a string). But, the real power of shell program doesn't come from the language itself, but from the diverse library that it can call upon -- any program.
    [Show full text]
  • ASCII Delimited Format Plug-In User’S Guide
    ASCII Delimited Format Plug-in User’s Guide Version 3.4 ASCII DELIMITED ......................................................................................................... 4 CREATING AN ASCII DELIMITED MESSAGE ....................................................... 4 ASCII DELIMITED EXTERNAL MESSAGE UI........................................................ 6 DEFINING AN ASCII DELIMITED MESSAGE FORMAT...................................... 7 ASCII DELIMITED FORMAT OPTIONS .............................................................................. 7 Delimiter ..................................................................................................................... 8 Message Options......................................................................................................... 9 Treat Entire Input/Output as a Single Message (Message Mode) ...................... 9 Treat Each Record as a Separate Message (Batch Mode) ................................ 10 Single Record Mode ......................................................................................... 10 Header/Trailer Option.............................................................................................. 11 ADDING A NEW FIELD.................................................................................................... 12 SPECIFYING FIELD PROPERTIES...................................................................................... 13 The Required Property.....................................................................................
    [Show full text]
  • STAT579: SAS Programming
    Note on homework for SAS date formats I'm getting error messages using the format MMDDYY10D. even though this is listed on websites for SAS date formats. Instead, MMDDYY10 and similar (without the D seems to work for both hyphens and slashes. Also note that a date format such as MMDDYYw. means that the w is replaced by a number indicating the width of the string (e.g., 8 or 10). SAS Programming SAS data sets (Chapter 4 of Cody book) SAS creates data sets internally once they are read in from a Data Step. The data sets can be stored in different locations and accessed later on. The default is to store them in WORK, so if you create a data set using data adress; the logfile will say that it created a SAS dataset called WORK.ADDRESS. You can nagivate to the newly created SAS dataset. In SAS Studio, go to the Libraries Tab on the left (Usually appears toward the bottom until you click on it). Then WORK.ADDRESS should appear. SAS Programming SAS data sets SAS Programming SAS data sets SAS Programming Making datasets permanent You can also make SAS datasets permanent. This is done using the libname statement. E.g. SAS Programming Permanent SAS datasets The new dataset should be available to be accessed directly from other SAS programs without reading in original data. This can save a lot of time for large datasets. If the SAS dataset is called mydata, the SAS dataset will be called mydata.sas7bdat, where the 7 refers to the datastructures used in version 7 (and which hasn't changed up to version 9).
    [Show full text]
  • Positive Pay Format Guide
    Positive Pay Format Guide Check File Import Contents Contents ........................................................................................................................................................ 1 I. Supported File Types ............................................................................................................................. 2 A. Delimited Text Files ........................................................................................................................... 2 B. Microsoft Excel Files.......................................................................................................................... 2 C. Fixed-width Text Files ....................................................................................................................... 2 D. Header and Trailer Records .............................................................................................................. 2 II. File Data Requirements ......................................................................................................................... 3 A. Required Columns ............................................................................................................................. 3 B. Optional Columns.............................................................................................................................. 3 Positive Pay 1 of 3 BankFinancial, NA Format Guide 11-2016-1 I. Supported File Types Positive Pay supports the following three types of issued files: A. Delimited
    [Show full text]
  • Teach Yourself Perl 5 in 21 Days
    Teach Yourself Perl 5 in 21 days David Till Table of Contents: Introduction ● Who Should Read This Book? ● Special Features of This Book ● Programming Examples ● End-of-Day Q& A and Workshop ● Conventions Used in This Book ● What You'll Learn in 21 Days Week 1 Week at a Glance ● Where You're Going Day 1 Getting Started ● What Is Perl? ● How Do I Find Perl? ❍ Where Do I Get Perl? ❍ Other Places to Get Perl ● A Sample Perl Program ● Running a Perl Program ❍ If Something Goes Wrong ● The First Line of Your Perl Program: How Comments Work ❍ Comments ● Line 2: Statements, Tokens, and <STDIN> ❍ Statements and Tokens ❍ Tokens and White Space ❍ What the Tokens Do: Reading from Standard Input ● Line 3: Writing to Standard Output ❍ Function Invocations and Arguments ● Error Messages ● Interpretive Languages Versus Compiled Languages ● Summary ● Q&A ● Workshop ❍ Quiz ❍ Exercises Day 2 Basic Operators and Control Flow ● Storing in Scalar Variables Assignment ❍ The Definition of a Scalar Variable ❍ Scalar Variable Syntax ❍ Assigning a Value to a Scalar Variable ● Performing Arithmetic ❍ Example of Miles-to-Kilometers Conversion ❍ The chop Library Function ● Expressions ❍ Assignments and Expressions ● Other Perl Operators ● Introduction to Conditional Statements ● The if Statement ❍ The Conditional Expression ❍ The Statement Block ❍ Testing for Equality Using == ❍ Other Comparison Operators ● Two-Way Branching Using if and else ● Multi-Way Branching Using elsif ● Writing Loops Using the while Statement ● Nesting Conditional Statements ● Looping Using
    [Show full text]
  • Installing and Configuring PHP
    05 6205 CH03.qxd 11/20/03 11:27 AM Page 51 CHAPTER 3 Installing and Configuring PHP In the last of the three installation-related chapters, you will acquire, install, and configure PHP and make some basic changes to your Apache installation. In this chapter, you will learn . How to install PHP with Apache on Linux/Unix . How to install PHP with Apache server on Windows . How to test your PHP installation . How to find help when things go wrong . The basics of the PHP language Current and Future Versions of PHP The installation instructions in this chapter refer to PHP version 4.3.3, which is the current version of the software. The PHP Group uses minor release numbers for updates containing security enhancements or bug fixes. Minor releases do not follow a set release schedule; when enhancements or fixes are added to the code and thor- oughly tested, the PHP Group will releases a new version, with a new minor version number. It is possible that by the time you purchase this book, the minor version number will have changed, to 4.3.4 or beyond. If that is the case, you should read the list of changes at http://www.php.net/ChangeLog-4.php for any changes regarding the installation or configuration process, which makes up the bulk of this chapter. Although it is unlikely that any installation instructions will change between minor version updates, you should get in the habit of always checking the changelog of software that you install and maintain. If a minor version change does occur during the time you are reading this book, but no installation changes are noted in the 05 6205 CH03.qxd 11/20/03 11:27 AM Page 52 52 Chapter 3 changelog, simply make a mental note and substitute the new version number wherever it appears in the installation instructions and accompanying figures.
    [Show full text]
  • Understanding the Command-Line Interface
    Understanding the Command-Line Interface This chapter helps you understand the command-line interface. • Information About the CLI Prompt, on page 1 • Command Modes, on page 2 • Special Characters, on page 5 • Keystroke Shortcuts, on page 5 • Abbreviating Commands, on page 7 • Completing a Partial Command Name, on page 8 • Identifying Your Location in the Command Hierarchy, on page 8 • Using the no Form of a Command , on page 9 • Configuring CLI Variables, on page 10 • Command Aliases, on page 12 • Command Scripts, on page 14 • Context-Sensitive Help , on page 16 • Understanding Regular Expressions, on page 17 • Searching and Filtering show Command Output, on page 19 • Searching and Filtering from the --More-- Prompt, on page 23 • Using the Command History, on page 24 • Enabling or Disabling the CLI Confirmation Prompts, on page 26 • Setting CLI Display Colors, on page 26 • Sending Commands to Modules, on page 27 • BIOS Loader Prompt, on page 28 • Examples Using the CLI , on page 28 Information About the CLI Prompt Once you have successfully accessed the device, the CLI prompt displays in the terminal window of your console port or remote workstation as shown in this example: User Access Verification login: admin Password:<password> Cisco Nexus Operating System (NX-OS) Software TAC support: http://www.cisco.com/tac Copyright (c) 2002-2009, Cisco Systems, Inc. All rights reserved. Understanding the Command-Line Interface 1 Understanding the Command-Line Interface Command Modes The copyrights to certain works contained in this software are owned by other third parties and used and distributed under license. Certain components of this software are licensed under the GNU General Public License (GPL) version 2.0 or the GNU Lesser General Public License (LGPL) Version 2.1.
    [Show full text]
  • Command-Line Interface User's Guide
    Storage Productivity Center for Replication for System z Version 4.2.2.1 Command-line Interface User's Guide SC27-2323-06 Storage Productivity Center for Replication for System z Version 4.2.2.1 Command-line Interface User's Guide SC27-2323-06 Note Before using this information and the product it supports, read the information in “Notices” on page 133. This edition applies to version 4, release 2, modification 2, fix pack 1 of IBM Tivoli Storage Productivity Center for Replication for System z (product number 5698-B30 and 5698-B31) and to all subsequent releases and modifications until otherwise indicated in new editions. This edition replaces SC27-2323-05. © Copyright IBM Corporation 2005, 2011. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. Contents Figures ...............v lslss .................55 lsmc .................57 Tables ...............vii lspair ................59 lsparameter ..............63 lspath ................65 About this guide ...........ix lspool ................67 Intended audience ............ix lsrolepairs ...............70 Command-line interface conventions ......ix lsrolescpset ..............73 Presentation of command information ....ix lssess ................75 Command entry ............xi lssessactions ..............78 Command modes ...........xii lssessdetails ..............80 User assistance for commands .......xiv lssnapgrp ...............82 Output from command processing .....xv lssnapgrpactions.............85 Accessing the
    [Show full text]
  • The Linux Command Line
    The Linux Command Line Second Internet Edition William E. Shotts, Jr. A LinuxCommand.org Book Copyright ©2008-2013, William E. Shotts, Jr. This work is licensed under the Creative Commons Attribution-Noncommercial-No De- rivative Works 3.0 United States License. To view a copy of this license, visit the link above or send a letter to Creative Commons, 171 Second Street, Suite 300, San Fran- cisco, California, 94105, USA. Linux® is the registered trademark of Linus Torvalds. All other trademarks belong to their respective owners. This book is part of the LinuxCommand.org project, a site for Linux education and advo- cacy devoted to helping users of legacy operating systems migrate into the future. You may contact the LinuxCommand.org project at http://linuxcommand.org. This book is also available in printed form, published by No Starch Press and may be purchased wherever fine books are sold. No Starch Press also offers this book in elec- tronic formats for most popular e-readers: http://nostarch.com/tlcl.htm Release History Version Date Description 13.07 July 6, 2013 Second Internet Edition. 09.12 December 14, 2009 First Internet Edition. 09.11 November 19, 2009 Fourth draft with almost all reviewer feedback incorporated and edited through chapter 37. 09.10 October 3, 2009 Third draft with revised table formatting, partial application of reviewers feedback and edited through chapter 18. 09.08 August 12, 2009 Second draft incorporating the first editing pass. 09.07 July 18, 2009 Completed first draft. Table of Contents Introduction....................................................................................................xvi
    [Show full text]
  • DATALINES, Sequential Files, CSV, HTML, and More
    SUGI 31 Tutorials Paper 228-31 DATALINES, Sequential Files, CSV, HTML and More – Using INFILE and INPUT Statements to Introduce External Data into the SAS® System Andrew T. Kuligowski, Nielsen Media Research ABSTRACT / INTRODUCTION The SAS® System has numerous capabilities to store, analyze, report, and present data. However, those features are useless unless that data is stored in, or can be accessed by, the SAS System. This presentation is designed to review the INFILE and INPUT statements. It has been set up as a series of examples, each building on the other, rather than a mere recitation of the options as documented in the manual. These examples will include various data sources, including DATALINES, sequential files, CSV files, and HTML files. GETTING STARTED – BASIC INFILE / INPUT with DATALINES In order to bring data from an external source into your SAS session, the user must provide the answers to a couple of simple questions: Where is the data, and what does it look like? The INFILE statement will define the data source and provide a few tidbits of information regarding its form, while the INPUT statement will define the format of the data to be processed. /* INTRO EXAMPLE */ NOTE: Invalid data for ConfName in DATA SasConf; line 9 1-9. INFILE DATALINES; NOTE: Invalid data for ConfCity in INPUT ConfName line 9 16-18. ConfYear NOTE: Invalid data for ConfST in ConfCity line 9 20-28. ConfST ; RULE: ----+----1----+----2----+----3--- DATALINES; 9 SUGI 2006 San Francisco CA SUGI 2006 San Francisco CA ConfName=. ConfYear=2006 ConfCity=. PHARMASUG 2006 Bonita Springs FL ConfST=.
    [Show full text]