Intelligent Code Comprehensibility Index: A Cognitive-Based Metric for Enhancing Code Review and Documentation

Abstract

As software systems become increasingly complex, developers face more challenging tasks in understanding, maintaining, and evolving code. Traditional software metrics like Lines of Code, Cyclomatic Complexity, and Halstead metrics provide structural insights but often fail to capture the cognitive aspects of code comprehension. This paper introduces the Intelligent Code Comprehensibility Index, a new multi-dimensional metric framework based on Cognitive Load Theory. The Intelligent Code Comprehensibility Index assesses code comprehensibility by examining three key dimensions: Structural Complexity, Documentation Quality, and Naming Quality. Each dimension targets specific cognitive loads, Intrinsic, Extraneous, and Germane, by including syntactic metrics for semantic alignment and drawing on empirical research from software engineering and neuroscience. The proposed framework aims to offer a more comprehensive and cognitively aligned method for evaluating and improving source code understandability, thereby boosting developer productivity and code quality.