Programmer qualities (Was: MP3 Format Page)

[onlyonemac]

We could at least have a page saying "here are some common file formats that you will almost certainly want to be able to read, but we're not going to be nice enough to explain them to you even though we've already figured them out so we'll make you go read the specifications yourself, which you can find links to in the list below".

Oh, and by the way it took me about two weeks to find any documentation on the MIDI file format that went beyond "the file stores a list of MIDI events" and actually explained what the bytes in the file mean. When I did eventually find something, it was written by some guy who was hacking around with his SB16 in the early 90s. If there is an official specification on the MIDI file format, Google certainly doesn't make it easy to find (and even when I have found specifications before, they're usually 100+ page documents that by the end of them your head is a big muddle of the words "header", "structure", "packet", and the names of a million other standards that you also have to read about before you can implement a 100% standards-compliant parser for the file format of which 90% is never going to be used because only 10% of the standard is actually applicable to real-world usage).

In other words, if someone's managed to figure out how to decode MP3 files on their OS then we need to know about it.

[Love4Boobies]

The first two Google hits for "MIDI" are to the MIDI Association's Web site and to the MIDI Wikipedia page. Both of them link directly to the specifications.

[onlyonemac]

The first two Google hits for "MIDI" are to the MIDI Association's Web site and to the MIDI Wikipedia page. Both of them link directly to the specifications.

As I say, there are plenty of resources regarding the MIDI protocol, I'm talking about MIDI files for which I struggled to find any information beyond "they store MIDI events". Also, I'm not registering an account with a website just to download a specification that I'm probably not going to understand if it even happens to contain the information that I'm looking for, which is unlikely.

When I Google "midi file format" I get

• http://www.ccarh.org/courses/253/handout/smf/
• http://www.music.mcgill.ca/~ich/classes ... ormat.html
• https://www.csie.ntu.edu.tw/~r92092/ref/midi/

The first doesn't tell me anything about the actual representation of the data in the file, the second one makes it sound so complicated that I can't understand it without reading and memorising the entire document first, and the third one does the same as the second one (but in a different way, making it impossible to understand them both if you read them together). The rest of the links explain only what a MIDI file is or what the different between type 0 and type 1 MIDI files and so on.

Eventually I found this document which explains what each sequence of bytes in the file means, how the values are encoded, and whatever else in a way that actually makes sense to me.

[Love4Boobies]

Oh, boy, what a conversation. Open the MIDI Association's specifications page again. Read the titles and their descriptions. Carefully! You can do this.

[Combuster]

So the conclusion is that your lack of interpretation skill rather than the lack of documentation itself makes you want a new source of information.

[onlyonemac]

So the conclusion is that your lack of interpretation skill rather than the lack of documentation itself makes you want a new source of information.

No, I want a source of information that doesn't require me to register an account and read hundreds of pages and still not understand how to actually implement anything.

And let's bear in mind that MIDI is nowhere near as complicated as MP3 or PNG or JPEG or any of those more common formats.

[Combuster]

I was referring to http://www.music.mcgill.ca/~ich/classes ... ormat.html - it's complete specification-wise, and even comes with code and examples.

Feel free to reject it, but don't go complaining there is no documentation and that we should be covering someone who's basically burning his own ships. That's particularly non-constructive with respect to the original topic of this thread.

[iansjack]

I want a source of information that doesn't require me to register an account and read hundreds of pages and still not understand how to actually implement anything.

Education can be a tricky process, but stick at it. It's worth it in the end.

An antipathy towards registering on web sites is going to be a serious handicap. Luckily (for you) you had no such inhibitions about registering on this site.

[onlyonemac]

An antipathy towards registering on web sites is going to be a serious handicap. Luckily (for you) you had no such inhibitions about registering on this site.

Because I intended to get some prolonged use out of the forum, not just download a single file that I'm not going to be able to understand.

[Love4Boobies]

I'm not sure what about that specification you find difficult to understand. I suspect you haven't really tried reading it, in the same way you didn't bother paying attention to the aforementioned Web page. If you ever want to get anywhere in the technical world, you need to learn how to read technical material and become self-reliant. Literacy is probably 80% of what makes a good engineer. I would hire a literate programmer over a clever one any day of the week.

[onlyonemac]

you didn't bother paying attention to the aforementioned Web page

I did read the page. It doesn't tell me what the actual bytes in the file will be, it just talks about "chunks" and "events".

I would hire a literate programmer over a clever one any day of the week.

Bad idea. I would far rather get elegant bug-free code than spaghetti code that quotes a bunch of standards in the comments. To me, the most important thing about programming is writing practical code that works efficiently, not being able to understand the technicalities of everything to the point that your code becomes a hackish mess. It's the difference between file parsers that define classes for every few bytes in the file and try to parse the file into a collection of these objects then process these objects to get another collection of objects in the format that the rest of the code expects, and file parsers that read the file as a stream and straight away produce a collection of objects ready for the rest of the code to process. The latter file parser may not be breaking the file down in the exact way that it's documented in the standard, but it's going to be faster, less prone to bugs, and work perfectly fine in all practical situations.

[iansjack]

I would hire a literate programmer over a clever one any day of the week.

I'm not convinced that there is a real difference. An illiterate programmer may think they are clever but they are kidding themselves. And you have to be reasonably clever to be literate when it comes to computer documentation.

[Love4Boobies]

You'd be surprised how often smart people don't put in enough of an effort and become useless. Luckly, you don't need to be a genius to program (for most tasks, it's enough to be literate and disciplined). Far from it, you see kids picking it up with relative ease but there aren't too many quantum physicist or neuroscientist kids out there. Obviously, I'm not advocating against hiring smart people but I was making a point about priorities.

@onlyonemac: It's actually people trying to be clever that usually end up writing unmaintainable code. When you have a choice between being clever/efficient and doing it in a simple manner, the latter is almost always the correct answer. And I wouldn't recommend non-compliance. Imagine parsing a huge code base, like Linux, with a non-compliant parser; you think you'll like the results?

[SpyderTL]

It's actually people trying to be clever that usually end up writing unmaintainable code. When you have a choice between being clever/efficient and doing it in a simple manner, the latter is almost always the correct answer.

Amen! I try to explain this to people on a daily basis, any way that I can. Some developers just can't help themselves. They pat themselves on the back for building systems that are so complex, it takes other people 10x longer to maintain it, until someone finally decides to throw it away and start over from scratch.

I don't understand why people make decisions that almost immediately make their lives more difficult. I guess some people think that building a complex solution proves that you are smart. Unfortunately, anyone can build something complex, given enough time. What is truly difficult is solving a complex problem in a simple way... A way that everyone can understand.

But most people don't want to hear that, apparently.

[onlyonemac]

Far from it, you see kids picking it up with relative ease but there aren't too many quantum physicist or neuroscientist kids out there.

Yeah, and have you seen the kind of code that they write?

When you have a choice between being clever/efficient and doing it in a simple manner, the latter is almost always the correct answer.

over-optimised < efficient, efficient > bloated. In short, don't mistake efficient code for over-optimised code (at which point is because unreadable/difficult to maintain), and don't mistake bloated code for simple code. Of the two implementation examples that I gave, the first would be bloated because it's doing more work than necessary, while the second would be efficient because it's doing just the work that's required to complete the task (and it's not over-optimised).

And I wouldn't recommend non-compliance. Imagine parsing a huge code base, like Linux, with a non-compliant parser; you think you'll like the results?

I never advocated non-compliance. What I did advocate was not supporting extensions to a standard and specific variants of a particular format/protocol when they're a) seldom used b) give you an undesirable amount of work and/or make your code ridiculously complicated and c) are beyond the scope of your project. I also mentioned that my experience with official standards documents is that they give you the full details of all of these additional variations and don't tell you the 10%, 50%, 75% or whatever of the standard that you need to implement to actually write code that works in 99% of cases and 100% of all cases that you care about.

Case in point: type 2 MIDI files do exist, but almost nobody uses them so unless you're writing a specialised application for recovering data from MIDI files you probably don't need to worry about them beyond "throw an error if the user has one". (Note: I said almost nobody - I'm not talking about parsing the entire Linux kernel codebase here, but an average-sized project picked at random from GitHub.) You don't need to implement every HTTP header and response code to write a working HTTP client that will allow you to browse the internet, but if you want to write a robust client that will work no matter what then you'll need to implement everything (and for laughs include HTCPCP in that as well).

It's about getting the balance between robustness/flexibility and complexity. And what I'm advocating is a category on the wiki for pages that say "here's how you can get xxx up and running on your OS" (e.g. "here's how you can get a working HTTP client" or "here's how you can get a working media player" or "here's how you can get a working image-loading library" or whatever else, we should probably include TCP/IP in there). I'm not saying that we should cover every detail of every protocol, but to give people the information that they need to turn their practically-useless OS into something with an interesting userspace that they can say "look, it even plays MP3 files!" instead of being restricted to "look, it can read a FAT filesystem!".

What's more, there are already OSdevers out there who have sifted through the standards documentation and figured out what's needed to make something usable, and there's no reason to not let them share it with the rest of us.