Abstract
In this essay I take what might seem a paradoxical position. I endorse the techniques that some programmers claim make code self-documenting and encourage the development of programs that do “automatic documentation.” Yet I also contend that these methods cannot provide the documentation necessary for reliable and maintainable code. They are only a rough aid, and even then help with only one or two aspects of documentation—not including the most important ones.
Index Terms
- Comments are More Important than Code: The thorough use of internal documentation is one of the most-overlooked ways of improving software quality and speeding implementation.
Recommendations
Speculative analysis for quality assessment of code comments
ICSE '21: Proceedings of the 43rd International Conference on Software Engineering: Companion ProceedingsPrevious studies have shown that high-quality code comments assist developers in program comprehension and maintenance tasks. However, the semi-structured nature of comments, unclear conventions for writing good comments, and the lack of quality ...
A Survey of Automatic Generation of Code Comments
ICMSS 2020: Proceedings of the 2020 4th International Conference on Management Engineering, Software Engineering and Service SciencesCode comments are a valuable form of documentation attached to code that is the most intuitive and efficient way for programmers to understand software code. Good code comments can help programmers quickly understand the role of source code and ...
Analyzing the co-evolution of comments and source code
Source code comments are a valuable instrument to preserve design decisions and to communicate the intent of the code to programmers and maintainers. Nevertheless, commenting source code and keeping comments up-to-date is often neglected for reasons of ...
Comments