4 ms·
I find this PR an interesting opportunity to discuss different types of documentation. I've internalized that there's a difference between the PR description,
by Oddskar 5y ago
I find this PR an interesting opportunity to discuss different types of documentation.
I've internalized that there's a difference between the PR description, commit messages, and code comments. For me there's different intended audiences for all three, and their contents should thus be shaped accordingly. This PR basically combines all three into one and uses that as the commit message, and I'm not sure of what to make of it. Is this good practice?
Personally I find the contents of the "#### Summary of Changes" list to be super-neat and helpful. But should these not be more helpful as comments inside the code? On the other hand, it does explain what the code is doing at this snapshot in time: which makes it more precise than comments in the code -- since future changes might eventually make those comments incorrect.
What's your take?
- edgyquant 5y agoPersonally I like for the dev to do little commits that document each change to a file and then when the branch is merged in you do a squash merge and each commit msg becomes a bullet point.
- andreareina 5y agoI realize this is specific to having an interface that makes it easy, but I find it valuable to step through each commit in a larger merge review. I'm not a fan of how e.g. bitbucket doesn't make it easy to browse the commit contents .
- franga2000 5y ago> On the other hand, it does explain what the code is doing at this snapshot in time: which makes it more precise than comments in the code -- since future changes might eventually make those comments incorrect. If changes are made to the code, the comments should be updated accordingly. Getting from code to a PR text is a non-obvious and difficult process and when parts of the code are updated, the trail is easily lost.
- Oddskar 5y agoI share the same opinion. While perhaps more brittle, it’s also immediately apparent