Executable Trigger-Action Comments Pengyu Nie, Rishabh Rai, Junyi Jessy Li, Sarfraz Khurshid, Raymond J. Mooney, and Milos Gligoric The University of Texas at Austin {pynie@,rrai.squared@,jessy@austin.,khurshid@ece.,mooney@cs.,gligoric@}utexas.edu ABSTRACT Wave project: “Remove this when HtmlViewImpl implements getAt- Natural language elements, e.g., todo comments, are frequently tributes”, etc.). We consider those comments where the trigger is used to communicate among the developers and to describe tasks expressed based on the state of the code repositories and actions that need to be performed (actions) when specific conditions hold require modifications of source or binary code. We call these com- in the code repository (triggers). As projects evolve, development ments trigger-action comments. processes change, and development teams reorganize, these com- Although trigger-action comments are ubiquitous, they are, like ments, because of their informal nature, frequently become irrele- other types of comments, written in natural language. Thus, as vant or forgotten. projects evolve, development processes change, and development We present the first technique, dubbed TrigIt, to specify trigger- teams reorganize, these comments frequently become irrelevant or action todo comments as executable statements. Thus, actions are forgotten. As an example, consider the following comment from executed automatically when triggers evaluate to true. TrigIt spec- the Apache Gobblin project [13]: “Remove once we commit any ifications are written in the host language (e.g., Java) and are evalu- other classes”. This comment, followed by an empty class, was in- ated as part of the build process. The triggers are specified as query cluded in revision 38ce024 (Dec 10, 2015) in package-info.java file statements over abstract syntax trees and abstract representation to force the javadoc tool to generate documentation for an empty of build configuration scripts, and the actions are specified as code package. In revision bbdf320 (Feb 4, 2016) classes were added to transformation steps. We implemented TrigIt for the Java pro- the package, but the comment (and the empty class in package- gramming language and migrated 20 existing trigger-action com- info.java file) remained in the code repository up to this date. Hav- ments from 8 popular open-source projects. We evaluate the cost ing pending actions, i.e., those actions that should have been done of using TrigIt in terms of the number of tokens in the executable because the triggers are satisfied, and outdated comments may comments and the time overhead introduced in the build process. have impact on program comprehension, and maintenance [28, 41]. Additionally, having comments written in an informal way presents CCS CONCEPTS a challenge for some software engineering tools, such as refactor- ings [12, 29, 30], as those tools may not know how to manipulate • → ; Software and its engineering Domain specific languages code snippets and identifiers embedded in comments [38]. ; Software maintenance tools We present the first technique, dubbed TrigIt, to specify trigger- action comments as executable statements; the triggers are evalu- KEYWORDS ated automatically at each build and actions are taken based on Todo comments, trigger-action comments, executable comments users’ specifications. TrigIt introduces a domain specific language (DSL) that can be used to specify triggers and actions over the ab- ACM Reference Format: Pengyu Nie, Rishabh Rai, Junyi Jessy Li, Sarfraz Khurshid, Raymond J. Mooney, stract syntax trees (AST) and build configuration scripts. Specifi- and Milos Gligoric. 2018. Executable Trigger-Action Comments. In Pro- cally, triggers are written as query statements over ASTs and build ceedings of ACM Conference (Conference’17). ACM, New York, NY, USA, configuration scripts. On the other hand, actions are encoded as 11 pages. https://doi.org/10.1145/nnnnnnn.nnnnnnn transformation steps on ASTs. To provide a natural access to the AST elements and improve maintenance, the TrigIt DSL is embed- ded in the host language. However, the semantics of the language 1 INTRODUCTION enables the executable trigger-action comments to be evaluated as arXiv:1808.01729v1 [cs.SE] 6 Aug 2018 Natural language elements, such as todo comments, are frequently part of the static program analysis phase. used to communicate among developers [28, 39, 41]. Some of these We implemented TrigIt for Java, such that triggers are writ- comments specify that a developer should perform an action if a ten using Java streams and actions are transformation steps of cus- trigger holds (e.g., from the Google Guava project: “Remove this tom ASTs. TrigIt analyzes executable code and modifies either guard once lazyStackTrace() works in Java 9”, from the Apache executable code, source code, or neither, depending on users’ con- figuration. This flexibility allows users to enforce execution of ac- Permission to make digital or hard copies of all or part of this work for personal or tions, for example during testing or during debugging of TrigIt classroom use is granted without fee provided that copies are not made or distributed for profit or commercial advantage and that copies bear this notice and the full cita- comments, without modifying their sources. If a user chooses to tion on the first page. Copyrights for components of this work owned by others than modify source code, the trigger would be automatically removed ACM must be honored. Abstracting with credit is permitted. To copy otherwise, or re- from source code once the actions are taken. As the result of our publish, to post on servers or to redistribute to lists, requires prior specific permission and/or a fee. Request permissions from [email protected]. design decisions, TrigIt should be integrated in the build process Conference’17, July 2017, Washington, DC, USA after the compilation step. We also developed a Maven plugin to © 2018 Association for Computing Machinery. evaluate the triggers after the compilation phase and prior to test- ACM ISBN 978-x-xxxx-xxxx-x/YY/MM...$15.00 https://doi.org/10.1145/nnnnnnn.nnnnnnn ing/packaging phase. 1 Conference’17, July 2017, Washington, DC, USA P. Nie, R. Rai, J.J. Li, S. Khurshid, R.J. Mooney, and M. Gligoric 1 // AbstractStreamingHasher.java 1 // FreemarkerResultMockedTest.java 2 protected AbstractStreamingHasher(int chunkSize, int bufferSize) { 2 public void testDynamicAributesSupport() throws Exception { ... 3 // TODO(kevinb): check more preconditions (as bufferSize >= chunkSize) 3 dispatcher.serviceAction(request, response, mapping); 4 // if this is ever public 4 // TODO : remove expectedJDK15 and if() aer switching to Java 1.6 5 if (trigItIsPublic()) 5 String expectedJDK15 = "<input type=\"text\" ...; 6 checkArgument(bufferSize >= chunkSize); 6 if (trigItJava6()) 7 checkArgument(bufferSize % chunkSize == 0); ... } 7 expectedJDK15 = "<input type=\"text\" ...; 8 8 String expectedJDK16 = "<input type=\"text\" ...; 9 @TrigtItMethod 9 ... 10 boolean trigItIsPublic() { 10 if (trigItJava6()) 11 return TrigIt.getMethod("<init>", int.class, int.class).isPublic(); } 11 assertEquals(expectedJDK16, result); 12 else Figure 1: An example trigger-action comment from the 13 if (result.contains("foo=\"bar\" ...)) Google Guava project and TrigIt encoding to illustrate an 14 assertEquals(expectedJDK15, result); implicit action. 15 else 16 assertEquals(expectedJDK16, result); ... } We evaluated TrigIt by manually migrating 20 existing trigger- 17 action comments to the TrigIt DSL; all the comments are from 8 18 @TrigItMethod popular open-source projects available on GitHub. In our experi- 19 boolean trigItJava6() { ments, we report the complexity of TrigIt statements measured 20 return TrigIt.getJavaVersion().greaterEqualThan(TrigIt.JAVA6); } in terms of the number of tokens in the specifications and over- Figure 2: An example trigger-action comment from the head introduced by the tool in the build process. TrigIt does not Apache Struts project and TrigIt encoding to illustrate a introduce any overhead at runtime. Our results show that TrigIt trigger based on build configuration. introduces negligible overhead in the build process, and triggers and actions are simple to encode. 1 // Mapper.java The main contributions of this paper include: 2 TODO: make this protected once Mapper and FieldMapper ⋆ Idea: We introduce an idea to encode trigger-action comments, 3 are merged together currently written in natural language, as executable statements 4 public final String simpleName() { in the host language. Having executable trigger-action comments 5 return simpleName; 6 } enables their maintenance (e.g., refactoring), testing, and auto- 7 matic evaluation of the triggers and actions when the state of 8 @TrigItMethod the code repository changes. 9 public static void checkMerge() { ⋆ Tool: We implemented our idea in a tool, dubbed TrigIt, for 10 if(!TrigIt.hasClass("Mapper") || !TrigIt.hasClass("FieldMapper")) { Java. TrigIt statements are written in a language embedded in 11 TrigIt.getMethod(simpleName()).setProtected(); Java and perform queries and actions over ASTs. TrigIt inter- 12 } poses between compilation and execution, and thus does not in- 13 } troduce any runtime overhead. Figure 3: An example trigger-action comment from the Elas- ⋆ Evaluation: We evaluated TrigIt by manually migrating exist- ticsearch project and TrigIt encoding to illustrate an ex- ing comments, and measuring overhead in terms of the lines of plicit action. code and execution time during the build