Towards Context-Aware Code Comment Generation (2020)

Abstract: Code comments are vital for software maintenance and comprehension, but many software projects suffer from the lack of meaningful and up-to-date comments in practice. This paper presents a novel approach to automatically generate code comments at a function level by targeting object-oriented programming languages. Unlike prior work that only uses information locally available within the target function, our approach leverages broader contextual information by considering all other functions of the same class. To propagate and integrate information beyond the scope of the target function, we design a novel learning framework based on the bidirectional gated recurrent unit and a graph attention network with a pointer mechanism. We apply our approach to produce code comments for Java methods and compare it against four strong baseline methods. Experimental results show that our approach outperforms most methods by a large margin and achieves a comparable result with the state-of-the-art method.

## introduction high-quality code comments are important for software maintenance. yet, few software projects adequately document the code @xcite . one way to overcome the lack of human-written comments, and guard against mismatch and obsolete comments is to automatically generate them. classical approaches for auto-comment generation use hand-crafted templates to produce code descriptions @xcite @xcite , but suffer from poor scalability and high maintenance cost due to the expensive overhead of writing comment templates. more recent work takes a learning-based approach by employing neural network (nn) models developed for natural language processing tasks like machine translation to automatically generate comments @xcite . compared to hand-written templates, a learningbased approach based on empirical data is more scalable and sustainable. the key to generating high-quality comments is to utilize as much relevant information as possible from the source code to infer the high-level algorithmic intents. prior work achieves this by converting a representation of the program, e.g., an abstract syntax tree (ast), into a sequential sequence where a sequential model like lstm can be applied to translate the token sequence into natural language descriptions @xcite @xcite . some more recent work has employed the graph convolution network (gcn) to directly operate on a graph representation, e.g., an adjacency matrix, of the ast @xcite . while promising, all existing learning-based approaches only capture information from the target function (or method) to be commented but fail to capitalize on the abundant information and algorithmic intentions available in a broader context like the definition of the callee functions or other information (like the purposes and semantic meanings of data variables) that can only be gleaned through relevant methods in the same class. because the programmer's strategic intentions are often encapsulated in a scope greater than a local function, ignoring such contextual information would miss massive opportunities. as a motivation example, consider the java code shown in figure 1 . here, our task is to describe the purpose of method append defined at lines 10 and 12. this example is from a real-life opensource project, where a developer-written comment is given. the human-written comment states that this method adds a component to a panel object and then moves to the next data column. because neither panel nor the next data column appears in the target function, existing approaches operate on the ast of this local method would fail to generate meaningful descriptions. simply inlining the callee function, append(control, int), does not offer the context of the panel object, which is also important for understanding the programmer intentions. if we could look at a broader context outside the target function, i.e., by leveraging the construction function, defaultformbuilder, and the callee function, we can then obtain much of the contextual information needed for generating a good quality comment text. the above example demonstrates the importance of leveraging broader contextual information for comment generation. in object-oriented programming, object classes are the building block for expressing algorithmic intentions. indeed, it is the class (but not a single local method) that forms the mental boundary of functionality. since a class encapsulates much of the calling relationship and semantic information that cannot be obtained from a local function, the global structural information in a class should not be ignored when we attempt to understand the purpose of a function. this paper thus presents a new code comment generation approach by leveraging the global structural information in object-oriented programming languages. doing so allows us to utilize much of the contextual information within a class to enhance function-level comment generation. as a departure from all prior methods that only consider local information during encoding, our approach employs a two-way encoding mechanism by considering both information within and outside the target function. we achieve this by simultaneously modeling the token sequence of the target function and a program graph that connects all methods of the same class to the target function. we then learn the approximate synergy between the information available within the local function and the wider class scope. a key challenge here is how to determine the importance and relevance of information available at code scopes. to this end, we design a novel decoder for the comment generation process by learning what information at both the local and class level should be emphasized. our encoder is composed of a local encoder for extracting information from the local function and a global encoder for extracting information at the class level. the decoder then decides which code segmentations within the class should be paid most attention to so that we can employ a pointer mechanism to copy words directly from the source code to generate comments. we apply our approach to generate functionlevel comments for java programs. we evaluate our approach on java methods collected from over 1,600 open-source repositories hosted on github, and compare it against four strong baseline methods of code comment generation. experimental results show that our approach consistently delivers higher-quality comments, improving blue and rouge by at least 7.7% and 5.1% (up to 87.1% and 68.3%), respectively. this paper makes the following contributions: ## our approach as depicted in figure 2 , our code comment generation framework consists of three innovative components. the local encoder, based on a bi-directional ## related work as a critical task in software engineering, code comment generation has been exploited with various solutions. in recent years, deep learning based methods has dominated this line of research, most of which follow an encoder-decoder framework and can produce readable comments. @xcite proposes an lstm based language model with attention mechanism to generate short description for c# and sql queries. @xcite exploits the transferred knowledge from automatic api summaries to enhance the generation of code comments. however, this kind of methods fail to utilize the structural characteristics of programming codes. more recent efforts explicitly adopt the ast structure to explore the structure of code. @xcite introduces ast sequences generated by structure-based traversal (sbt) as a structured summary of the code into the generation model. @xcite applies an rnn unit over ast trees to extract both semantic and syntactic information and design a special decoder code-gru for the generation process. @xcite decomposes ast trees into paths between leaf nodes and sample a certain amount from them as the structural input for the model. @xcite proposes to use both ast sequences and source code sequence as multiple input for model. @xcite proposes to employ gnn over ast structures to better extract structure information. our work, on the contrast, explores broader context, class-level neighboring functions, to introduce rich information for comment generation. ## conclusion we have presented a novel approach for automatic code comment generation, targeting objectoriented programming languages. unlike prior work that only leverages information of the target function, our approach leverages related methods of the same class to exploit the information available in a broader context to improve the quality of the generated comment. our novel learning framework extracts local information from the target function and global contextual information at the class level. experiment results show that our model can efficiently combine both local and classlevel information and generate more detailed and higher-quality comments over prior methods.