3 ms·

I feel like programmers often fail to grasp the distinction between example code and production-ready code. On one project, we made some example code available

I feel like programmers often fail to grasp the distinction between example code and production-ready code. On one project, we made some example code available, and people would copy and paste it into their project, change a few lines, and launch it into production. Then they were surprised it didn't handle this or that situation or deal with this or that detail. Yeah, no shit it doesn't handle those things, it's example code! You're supposed to read this code along with the documentation so you can get a gist of what the API is like. It's a learning aid, not a software deliverable. Your real code is going to be more complicated. This simplified code exists to get you past the "how the hell does all this fit together at a high level?" hurdle faster. Once you're over that hurdle, you can start on the real implementation.

thrower123 7y ago
Hopefully there is documentation; often there is not. It's borderline criminal that nearly all examples omit error-handling code, at least for the broad-strokes classes of errors that you, as the library author, know can and will occur. I hated Java's checked exceptions, but it did let you have some idea what kind of errors were expected to be possible. Most of the time I'm excavating deep layers of source code, monitoring and logging to see what the errors might be, and tossing in catch-all handlers to keep the stack from unwinding too far if at all in doubt.
- adrianmonk 7y ago
  Yeah, I agree with that. That is usually hard-won knowledge, too, so if it doesn't get transferred, that creates a lot of pain. Unfortunately, a lot of people hate writing documentation and just want to get it over with as quickly as possible. (Ability to create working software doesn't necessarily correlate with ability or desire to share knowledge.) Also, if you look at it in terms of incentives, it's tricky to reward people for making sure the documentation of gotchas is reasonably complete. By definition, these are things that people would probably not see until they're pointed out. So it's hard to tell if someone has really done it. (And when people are busy, things that aren't rewarded are unlikely to happen.)
dkarl 7y ago
I wonder if people who complain about this have thought about what it would be like for beginners to only get to see production code. Sometimes the cow needs to be spherical.
- ptyyy 7y ago
  This reminds me of that image of how to draw an owl. People forget that everyone starts somewhere and there is no magical jump from beginner level code to production code. Having good, well-explained examples of the beginner and intermediate were incredibly beneficial to me.
kissgyorgy 7y ago
We solved this by explicitly making the code examples non-copy-pasteable at all, for example include strings like "<put your URL here>" and things like that, so they won't even work by accident.

thrower123 7y ago

Hopefully there is documentation; often there is not. It's borderline criminal that nearly all examples omit error-handling code, at least for the broad-strokes classes of errors that you, as the library author, know can and will occur. I hated Java's checked exceptions, but it did let you have some idea what kind of errors were expected to be possible. Most of the time I'm excavating deep layers of source code, monitoring and logging to see what the errors might be, and tossing in catch-all handlers to keep the stack from unwinding too far if at all in doubt.

adrianmonk 7y ago
Yeah, I agree with that. That is usually hard-won knowledge, too, so if it doesn't get transferred, that creates a lot of pain. Unfortunately, a lot of people hate writing documentation and just want to get it over with as quickly as possible. (Ability to create working software doesn't necessarily correlate with ability or desire to share knowledge.) Also, if you look at it in terms of incentives, it's tricky to reward people for making sure the documentation of gotchas is reasonably complete. By definition, these are things that people would probably not see until they're pointed out. So it's hard to tell if someone has really done it. (And when people are busy, things that aren't rewarded are unlikely to happen.)

dkarl 7y ago

I wonder if people who complain about this have thought about what it would be like for beginners to only get to see production code. Sometimes the cow needs to be spherical.

ptyyy 7y ago
This reminds me of that image of how to draw an owl. People forget that everyone starts somewhere and there is no magical jump from beginner level code to production code. Having good, well-explained examples of the beginner and intermediate were incredibly beneficial to me.

kissgyorgy 7y ago

We solved this by explicitly making the code examples non-copy-pasteable at all, for example include strings like "<put your URL here>" and things like that, so they won't even work by accident.