Comment by BrandonM | Hacker News Reader

Comment by BrandonM | Hacker News Reader

Parent Full thread

I really doubt that's true. You're saying that instead of using a poorly-documented mencode filter to fade a video in and out, you'd rather have to write your own filter or not be able to use mencode for the job at all?

While working on a project with a tight deadline, I've needed complex functionality that wasn't well-documented, and I've needed complex functionality that wasn't there. When it wasn't there, I was forced to produce complex functionality that wasn't documented. If I'm generous enough to release that for others to use, reference, and modify for free, then the last thing I want to hear is somebody bitching about how I didn't document it well enough for them. I have other things to do, and for me it was a one-off project.

In a pinch, source code is documentation, and it's pretty hard to make an argument that undocumented source code is worse than nothing at all. At least then when you're implementing your nicely-documented tool (because you'd rather have documentation than get stuff done), you'll have a reference implementation to look at and test against.

Note: I'm not arguing that documentation isn't important, I absolutely agree that it is. I just think it's absurd to rank the importance of documentation above the stuff that it's documenting.

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