Comment by tsally | Hacker News Reader

Comment by tsally | Hacker News Reader

Parent Full thread

It's my personal preference, so it's true whether you doubt it or not. :-p

Using undocumented code is like programming in a language I hate. Mentally it's a really shitty experience and I'm not in a position where I have to settle for that. If I needed to do it to put food on the table, obviously I would.

You're also creating this false dichotomy between getting stuff done and documenting your code. I've never been in a position to have to choose between the two. If you have time to write a good program but not enough time to document it, I would question whether the program you wrote is actually good. If I'm writing a paper, sure I can spew shit out on a page for a couple hours and produce a "paper". But realistically if I'm actually going to produce a paper I need time for outlining and proofreading.

(Note that "documentation" isn't really what matters, it's that the code is understandable. If the code is self-documenting or the program is small enough, I consider that documented code.)

Quite often, "getting stuff done" and documenting your code is two separate steps. The example I made up above was not something I pulled out of the air. I've been doing a lot of different little jobs for a client, and one of those was to create a program that could automatically publish a finished video based on a raw video input (adding an intro and outro sequence, fading in and out, etc.). To do that, I used ffmpeg.

ffmpeg had recently dropped support for an old filter system and began using a new, not-fully-fleshed-out system. The filter creation process was pretty well documented, and there were a few well-documented filters. There was a filter or two that I needed which was documented poorly but had a couple usage examples, just enough to get me going. I was very grateful for these! Then there were a few filters I needed that weren't there. I had to write them, which involved some level of trial-and-error to get working correctly.

My line of work is not video filters. The work I typically do for clients does not involve video processing. If I quote a client an amount for a job, the more time I spend on a one-off job, the more money I'm subtracting from my hourly, and the longer until I move onto the next job. Quite literally, I can get more stuff done, or I can document something that I'll never use again.

Reply on news.ycombinator.com