I could hear Cherry (cherry@) clacking away on his hhkb making those massive
renaming changes in the uvm_physseg.c and related machine dependent code, and
here I was trying to figure out “troff” to write as of yet non-existant man
page[1] for the uvm_hotplug(9) API.
In the past 6 months of working with Cherry and NetBSD I never felt being this
close to computer science as compared to the last 10 years of my professional
work experience. These past 6 months of work made the past 10 years look like I
was in the realm of play school equivalent of working with computers. In my
journey in these 10 years, I always felt that testing and documentation of code
(in that order respectively), are the next best ways (other than writing the
code for the system itself) to understanding the working of a system, especially
large systems like the kernel of an operating system. But a feeling is not good
enough to validate your theory, you need to see it in action.
In the 10 years of industry experience, the two things I have seen least done is
testing of code, followed by documentation of the code. Not only people see
these jobs as a lowly job meant for the less privileged like the new intern who
just joined the company or some green guy who just joined the project. And this
has always been the case. Even in those darkest of times, I had seen these
pockets of light, code that was well tested and well documented, code that never
even acknowledged of it’s existence, code that just sat there quietly in a
corner, code that never took more CPU time that it needed, code who’s processes
were nice to other processes. I always wondered how such code was written. It
was the code that were the least tested and/or documented (or worse wrongly
documented) that always made the most noise and demanded attention from us.
Most of my work in the uvm_hotplug(9) was related to testing, and time had come
for this work to be actually documented not in some random text file that no one
will ever see, but as a “man” page within the NetBSD Kernel Developer’s
Manual. And as I sat in my revolving chair, phasing in and out of my day dreams
and days by-gone, trying to figure out “troff”, Cherry interjected, “Why don’t
you refer the pool(9) man page and use it as a reference to write up the
uvm_hotplug(9) man page?”, “Not a bad idea”, I told Cherry and started to go
through pool(9) man page source.
To see a man page behind the scenes was quite exciting for me, this is the first
time I am reading through “troff”, more importantly pool(9) acted as a good base
for me helping me to concentrate on writing up the content for
uvm_hotplug(9). My English (especially grammar) is not top of the line, but I
believe I can write up sufficiently coherent sentences to convey ideas
meaningfully without them being lost in translation.
When testing code, I was mostly writing tests for ideas that were discussed out
between Cherry and myself. So most of the time tests indicated things I wanted
to write as functional code. When documenting code via man pages, it was the
opposite experience I was trascribing the motivation / idea of the functional
code back into meaningful English sentences. And it was at this point I had the
epiphany that unit tests (done via Test Driven Development) and documentation
done in form of man pages were two sides of the same coin, one complementing the
other and suddenly things were clearer than ever.
In addition to the above I was able to even fix a bug[2] I found in the pool(9)
man page with a misaligned section, which I was able to submit as a patch back
to NetBSD community, even though it was a one liner diff, it felt good to
actually give back something.
FeelsGoodMan!!
References
- http://netbsd.gw.com/cgi-bin/man-cgi?uvm_hotplug++NetBSD-current
- http://mail-index.netbsd.org/source-changes/2016/12/24/msg080150.html