Working on a new Go project has once again illustrated to me that one of the subtle and time-consuming parts about learning a new language is learning how design good APIs for your code. As traditional I've learned this by throwing together a number of APIs and then realizing that they're clumsy and awkward in various ways.

Every language has a collection of API idioms ranging from the small scale to the large (and often some more idioms on how to document your APIs), and with them another collection of anti-idioms, things to avoid. Some of these are obvious from the design of the language (eg when the language makes something terribly awkward), but generally many of them are not. One example is creating a C API that involves calling a function with a large struct as a parameter (instead of a pointer to it) or having a function return such a large struct. This is generally going to be seen as a bad idea due to the memory copying involved, but C doesn't make this explicit and indeed it sort of looks natural.

It's been my experience that learning these API idioms just takes time and writing code in the language (although 'how to design good X APIs' documentation helps, if you bother to read it). It's through writing code that I discover what's surprisingly awkward despite the initial appeal, what doesn't work, what works gracefully, and often why all sorts of existing code has the API that it does. One inevitable consequence of this is API churn in your own code as you discover that some of your early clever ideas weren't so clever after all.

(Writing tests for your code helps with this because tests use your APIs, both external and internal, and so can expose awkward ones. My experience is that this isn't perfect by any means; tests always feel a bit awkward to me anyways and not all of my APIs are used by tests.)

By the way, I recommend writing API documentation in some form as a way of smoking out awkward APIs. When I find myself putting cautions into the comments or struggling to explain something in a way that makes it sound sensible, I know I have a problem. This is not a cure-all since it basically just hits the generally obvious stuff.

(I also find that sometimes I know that something is awkward and probably wrong but I don't yet know enough to figure out how to make it better. And sometimes it turns out that there doesn't seem to be a better way.)