The best programmers I know

> A reasonable place to start. But fair that you can't stop there if it isn't working.

It's not a reasonable place to start. You're basically talking about copy-paste coding. Google search, stack overflow, paste in the first answer. Afterwards, ask the dev if they know what they did and why it works, and they won't be able to answer because they don't know.

> Next step, in my opinion, is to look at the interface more closely to see if it provides any hints. It will most of the time if it is well designed.

The people I'm taking about can't and won't do that.

> Sure. That's what the test suite is for, though: To document for users full intent and usage. You're still not going to go to a reference for that. As an added bonus, it is self-validating, so none of the "is it me or is the reference incorrect?" rigamarole.

I'm getting an "I don't need comments because code is self-documenting" vibe here. I disagree with that. Prose is a better way to express many, many things related to code than the code itself or even its test.

Sure, the code is the most authoritative place to find what was implemented, but it's not the best way to find the why or the concepts and thought behind it.

Why not? If it works it works. Not everyone is concerned with receiving the award for best programmer.

> they won't be able to answer because they don't know.

I do understand that you are thinking of a specific person here, but broadly, you will know how it works more or less because you'll already know how you would implement yourself if you had to. But since someone's else code already did, no need to think about it further. This remains a reasonable place to start.

> but not the why

If you are not capturing "why" in your tests, what are you testing, exactly? The "what" is already captured in the implementation. You don't need that written down twice. Worse, if you do end up testing "what" you are bound to have to deal with broken tests every time you have to make a change. That is a horrid situation to find yourself in.

I do agree that writing useful tests is really hard, at least as hard as writing good reference material, and thus beyond the skill of most. But if you have to work with something built by the unskilled, all bets are off no matter which way you look.

> Why not? If it works it works. Not everyone is concerned with receiving the award for best programmer.

Ok, that clarifies things: programmers who avoid reading the docs to guess, or follow the "Google search, stack overflow, paste in the first answer" cycle are mediocre programmers. If they don't want to be good programmers (which what the article is talking about), they can keep doing what they're doing.

> If you are not capturing "why" in your tests, what are you testing, exactly?

You can't capture why in code. Your tests are a demonstration of the "what."

That depends on the beholder.

- A programmer who applies a laundry list of what they do to determine who makes for a "best" programmer, who doesn't guess themselves, is likely to exclude anyone who does.

- A business person is apt to consider someone who successfully delivers a product quickly by using someone else's code among the "best".

> You can't capture why in code.

Then you can't capture it in natural language either, making this whole thing moot. But I disagree with that idea.

> Your tests are a demonstration of the "what."

You have a point that some testing frameworks carve out a special declaration for "example" tests that are marked for inclusion in generated API docs. There might be a time and place for that kind of documentation, but that isn't the kind of testing I was thinking of. That isn't representative of the vast majority of the tests you will write. If it is, you're doing something wrong – or at very least aren't being fair to those who will consume your tests later.

In my laundry list, concern for the next guy is what separates the "best" programmers from the mediocre. But I understand why your laundry list differs.