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.
- 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.