There should be a website like "justtellmehow.com" with useful articles like this.
I found that lib and tool documentations written by their authors tend be to be too long. It's understandable since they are passionate about the subject and want to talk about every details, but it's not great when you just want to quickly add a lib to your project or use some tool.
This can of course go beyond programming. But, yes, there is a major lack in CS and CE of relaying on the INTENT.
- I can see the datasheet where this micro has 32 message objects and a FIFO mode - but please tell me how you INTENDED it to be used because after weeks of figuring out the obscure memory and buffer system it turns out you never INTENDED a fifo rollover. Ok, that would have been excellent info on Day1.
- Your framework has a couple of examples and each function is documented. Great, but imagine my surprise when it turns out I can’t access a ‘global’ memory object outside of your function because you never intended that to happen - and never thought to let me know.
- This is the entire concept of a WHY comment vs a WHAT comment. Don’t write //increments X+1 instead use //counter ticked here because new value is used during the loop, must be placed at the top, uint8 / rolls at 256 for an x++ example. WHY comments made a big difference in the readability of my code. The goal is to relay intent.
The thing is, you don’t want to rigidly be stuck to someone else’s idea - but it’s extremely helpful to know how they planned for you use this because maybe the choices they made do make sense. Oh use an array of this memory type instead of casting it all to a class/structure! Yea, that’s fine and will be more efficient to search through etc etc.
I don’t need know why but engineers are really bad at telling you what they intended when making the product.
For using Go specifically, there is https://gobyexample.com/ which I have found to be a huge help. I'm not sure that's exactly what you're talking about, though.
I found that lib and tool documentations written by their authors tend be to be too long. It's understandable since they are passionate about the subject and want to talk about every details, but it's not great when you just want to quickly add a lib to your project or use some tool.