Comment by drothlis | Hacker News Reader

Comment by drothlis | Hacker News Reader

Parent Full thread

I don't know if this is what you mean, but I use version-control diff, log, and annotate ("blame") extensively for finding the commit that introduced a particular feature, in the hope that the commit message or the diff for the entire changeset will shed some light.

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?

[1] http://david.rothlis.net/emacs/basic_c.html#annotate

[2] http://david.rothlis.net/d/templates/

Your emacs guide looks awesome. I didn't realize just how powerful emacs can be for this version control browsing. I'm going to go through it in its entirety.

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.

Reply on news.ycombinator.com