One of the first things that I learned as a professional software engineer was to "ignore the comments" as they were generally out of sync with the code (sometimes completely so).
Unfortunately if you want to understand software you need to actually be able to read software - sorry (for protocols other than Bitcoin there are RFC's but am pretty sure they will not be much easier to read than code for your average Joe either).
Topic: Documentation is not just an explanation on how the code works. It is much mo (Read 437 times)
January 26, 2016, 12:37:37 PM
January 26, 2016, 12:35:00 PM
And who is supposed to read that? Because , you know, the engineers know how it works, and the users do not necessarily have to.
January 26, 2016, 10:50:07 AM
Coding requires communication skills
Making something is fun! Especially when you make something that no one has ever thought of. That doesn’t happen frequently AFK. However, when we’re in front of our computers, we make the impossible happen every day. We’re armed with the power of microchips that can do calculations at speeds not possible even by the fastest people in the world. Our lives have become significantly easier by this. As with all things in society, all of this has been possible because of our collective effort. As the title might imply, the emphasis on that previous sentence is on ‘collective’. We work together to achieve great things, because individually we are nothing. Unless we’re Superman, then OK, but for the part of the world that are not DC Comic fans and don’t believe in Superman, we need to work together.
Our almighty lord Satoshi has blessed us with this idea of the blockchain, distributed databases, bitcoin, which has spawned a breadth of possibilities not even thought of before. Just as Linus before him, s/he knew that the success of this idea is contingent on its openness, thus this project was open sourced from its inception. Now that we’re building upon this, shouldn’t we continue in the same steps? Don’t we have a duty to work collectively to create stuff that makes the world a better place to live in? You may argue that we do! Of course we do, we open source everything. Provide all the source code on repositories, anyone with an internet connection can get it and use it. Yes we do, but is that good enough? Imagine Boeing building a plane, and just giving it to people. Or NASA building a space ship, putting some people in it, and just telling them to give us a call when they get to Mars. Or the worst case scenario, imagine IKEA selling its products with no manual! Yes, creating something, however wonderful, is utterly useless without any documentation on how to use it.
https://bitsapphire.com/coding-requires-communication-skills/
Making something is fun! Especially when you make something that no one has ever thought of. That doesn’t happen frequently AFK. However, when we’re in front of our computers, we make the impossible happen every day. We’re armed with the power of microchips that can do calculations at speeds not possible even by the fastest people in the world. Our lives have become significantly easier by this. As with all things in society, all of this has been possible because of our collective effort. As the title might imply, the emphasis on that previous sentence is on ‘collective’. We work together to achieve great things, because individually we are nothing. Unless we’re Superman, then OK, but for the part of the world that are not DC Comic fans and don’t believe in Superman, we need to work together.
Our almighty lord Satoshi has blessed us with this idea of the blockchain, distributed databases, bitcoin, which has spawned a breadth of possibilities not even thought of before. Just as Linus before him, s/he knew that the success of this idea is contingent on its openness, thus this project was open sourced from its inception. Now that we’re building upon this, shouldn’t we continue in the same steps? Don’t we have a duty to work collectively to create stuff that makes the world a better place to live in? You may argue that we do! Of course we do, we open source everything. Provide all the source code on repositories, anyone with an internet connection can get it and use it. Yes we do, but is that good enough? Imagine Boeing building a plane, and just giving it to people. Or NASA building a space ship, putting some people in it, and just telling them to give us a call when they get to Mars. Or the worst case scenario, imagine IKEA selling its products with no manual! Yes, creating something, however wonderful, is utterly useless without any documentation on how to use it.
https://bitsapphire.com/coding-requires-communication-skills/
Jump to: