Introduction
In programming, while it is ideal to convey information solely through source code, there are limitations. This is especially true in team development, where pull requests (PRs) and source code comments become essential. This article explains the appropriate use and differentiation of these tools.
Importance of Pull Requests
PRs are a means to show code changes to the team and receive reviews. The main goal is to improve code quality.
Readers of Pull Requests
There are primarily two types of readers for PRs:
- Code Reviewers: Those who review the PR
- Code Modifiers: Those who investigate the PR to understand the history of code changes
Information to Include in a Pull Request
- Purpose of the Change: Why the change was made
- Main Changes: Overview of the modifications
- Scope: Range of the modifications
- Testing: Items tested and verification points
- Design/Implementation Considerations: Background of technical decisions
- Related Issues: Information on related tickets
Basically, include explanations that span multiple files or modifications, rather than what can be explained in code. If code explanations are necessary, it is preferable to write source code comments as mentioned later. However, if not suitable, supplement with inline review comments on the PR for easier understanding.
Importance of Source Code Comments
Source code comments are written to explain the behavior and intent of the code. The goal is to enable the reader to efficiently use and modify the code.
Readers of Source Code
There are also two types of readers for source code:
- Code Users: Those who want to know how to correctly use the code
- Code Modifiers: Those who modify the code to avoid bugs
Information to Include in Source Code Comments
- Purpose of Functions and Classes: What the function or class is for
- Usage of Functions and Classes: Typical usage examples of classes or functions
- Explanation of Complex Processes: Explanation of difficult-to-understand logic or algorithms
- Notes and TODOs: Points to improve or be aware of in the future
- External Reference Resources: URLs of referenced pages, etc.
Source code comments should pertain to specific files. Again, there is no need to rewrite what can be expressed in the code.
Conclusion
PRs and source code comments play an important role in team development. By understanding and appropriately using each, we can achieve improved code quality and efficient communication.
Discover more from Coursity
Subscribe to get the latest posts sent to your email.