Unhappy with code review tools: can’t we do better?
I’ve been unhappy with code review tools for a long time now. What I want to do:
I want to write
- this is the core of the change
- these are obvious supporting changes
- this is what I’m unsure about
The crazy thing is: I can partly do that in an email, just selecting small commits and comment between them.
But actually I would need to be able to re-order individual hunks of the change so they fit the explanation.
What I can do instead
- create a code review from multiple commits
- which becomes a file-listing ordered by name of the file with the change. Then I can
- intersperse comments to explain why I do the change. But ordered by the code and filenames.
Update: a minimal step into the right direction might be to be able to highlight files in the code review: „start here“.
Update 2: Folding comments could also be useful: „this just renames file Alice to Carol and adjusts the imports“. Ideally validated.
I would like to have something like this
diff -r 40e8ef29748a politik/kommentare.org
We need better code review tools.
--- a/politik/kommentare.org Tue Jun 25 09:42:12 2024 +0200
+++ b/politik/kommentare.org Fri Jun 28 07:11:38 2024 +0200
@@ -34,0 +44,7 @@
# The essential change: Add a requirements entry.
# Ask people who still review on mailing lists whether they need more.
+#+begin_src requirement :noweb-ref reasoning-story-based-review
+I want to write
+
+- this is the core of the change
+- these are obvious supporting changes
+- this is what I’m unsure about
+#+end_src
@@ -34,0 +57,5 @@
# Limitations of existing tools to compare — put at the end of the article
# This may need checking: Do you know tools which support more?
# Am I unfair to existing tools?
+- create a code review from multiple commits
+- which becomes a file-listing ordered by name of the file with the
+ change. Then I can
+- intersperse comments to explain why I do the change. But ordered by
+ the code and filenames.
@@ -32,3 +32,14 @@
#+toc: headlines 2
# Reasoning: the article heading; do you know a better structure?
+* Unhappy with code review tools: can’t we do better?
+ :PROPERTIES:
+ :CUSTOM_ID: unhappy-code-review
+ :END:
+
+I’ve been unhappy with code review tools for a long time now.
+
+
+What I want to do:
+
# here we need the requirements for the flow of the article
+{{{reasoning-story-based-review}}}
@@ -34,0 +49,10 @@
+
+The crazy thing is: I can partly do that in an email, just selecting
+small commits and comment between them.
+
+But actually I would need to be able to re-order individual hunks of
+the change so they fit the explanation.
+
+
+What I can do instead:
+
# here comes the problems listing
@@ -34,0 +67,9 @@
# end the article with a practical example
+
+
+Something like this:
+
+#+begin_src diff
+diff -r 40e8ef29748a politik/kommentare.org
+We need better code review tools.
+--- a/politik/kommentare.org Tue Jun 25 09:42:12 2024 +0200
++++ b/politik/kommentare.org Fri Jun 28 07:56:52 2024 +0200
+ ...