Seriously: in most cases it's possible to split up a 30-line patch into 5 separate patches that, applied in order, monotonically improve your code base and are easier to review, in total, than one larger patch. Changesets are cheap, and we should be optimizing them for easy review, so any eyeball we get can see what's going on.
I suppose I could create patches as I am actively solving the problem, but at that point my code may very well be a mess that I'd have to clean up each time.
Of course all of that is moot if your problem naturally segments into several patches, if nothing else than simply by the virtue of being larger than a 30-line patch or involving several mostly independent components.
git-cola is a good GUI to visually stage chunks into separate commits. I haven't really used git-cola's other functionality, but I really like its visual staging features.
If you use, say, git, you might commit every single, tiny change separately, on a private (local) branch; then use `git rebase --interactive` to reorder/merge the commits as necessary. This is the easiest way I have found, but it still involves more work.
If you wanted to take it further, you could have your editor automatically commit on every save, with a post-commit hook that takes your changes into a staging area, compiles/tests, and provides a report for each commit.
Even aside from the artifact of diff, I don't think this situation is analogous to short functions at all. The big difference is that commit logs are much more serial in nature. If I break one commit down to a sequence of 5 simpler commits they will almost always be read in that order, with context preserved.
I'm ambivalent about long functions, but am much more draconian about complex commits: http://github.com/akkartik/wart
If there were people doing this, I'd see the odd little tool to make it easier, to annotate logs and so on. But there are no signs of this.
If nobody is looking to commit histories for narrative, perhaps it's because the commit history is the wrong place for it. Since history is immutable it's really hard to have a coherent narrative of a project. Trying to do that ends up with commit messages like "final version", "really final version", "final version this time for sure", etc. My attitude has been to leave the narrative up to the reader to reconstruct. All I can do is talk about this particular point in time.
Hmm, even if the globally coherent narrative is impossible, perhaps it's worth trying to keep a piecewise-coherent history. I tend to have 'section boundaries' where I start a new feature/subsystem/narrative[1]. Perhaps I should demarcate them with "=== " or something so they're easier to see in the log.
[1] Again, I never attempt to demarcate where a feature or narrative ends, because that's impossible to judge without hindsight.
Emacs has tools that make this fairly easy with any version-control system supported by Emacs.[1]
Presumably some of the web-based browsers provided by version-control tools offer the same functionality, but every one I have seen lacks the crucial feature of re-running "annotate" again starting from the revision just before the revision that last changed line X. Otherwise you're looking at "annotate" output for a whitespace change, and to get to something useful you must manually get the log for the file, find the previous revision to what "annotate" was reporting, and run "annotate" again from there.
I've also toyed with storing documentation in commit messages themselves. For example, I wrote a blog post[2] where all the code samples in the article reflect files tracked in a version-control system, evolutions in the code samples are different commits, and the text of the article itself is taken from specially-annotated text in the commit messages. Turns out (surprise surprise!) that this is totally unmaintainable, but it was a fun exercise.
Do you have any concrete examples/writeups of your approach?
I've tried to put some tools together several times (trying to integrate with vim) without success. Mostly my approach boils down to being more aware of the commit history as I navigate. When I find myself in a new codebase I start with browsing the initial commits. Then as I go over the codebase I aggressively use git log <path>, and might drill down to look at specific, tantalizing commits.
One of my project ideas is a 'wikipedia for open source' where anybody can browse the code for open source projects both in space and in time (like emacs seems to allow), and add annotations to specific revisions. While reading, annotations from previous revisions are rendered as well, but every annotation would give some indication of age (like '350 days ago' on HN) which would help the reader gauge if it might be out of date. This would allow readers to collaboratively say, "read this snapshot first if you're new to the project" and so on.
I also try to make the logs in my projects easier to read. Here's how I got started with that: http://akkartik.name/codelog.html
IMO the big reason lots of great hackers mistrust code comments is that when you add a comment it hangs around forever by default, unless someone takes the time to decide to delete it. Attaching comments to the commit log or to annotations on a specific revision helps with this.
---
"I wrote a blog post where all the code samples in the article reflect files tracked in a version-control system, evolutions in the code samples are different commits, and the text of the article itself is taken from specially-annotated text in the commit messages."
Compare http://akkartik.name/countPaths.html :)
You can make your approach more maintainable if you give up on keeping the prose coherent. The biggest problem with documentation is that it doesn't get written most of the time. I focus on mechanisms that make it more likely I will provide that one key sentence for future readers. And -- like in wikipedia -- I assume the reader is reading critically enough to be able to handle glitches.