|
At the very top of the file, I add: /* FILENAME: test.php STATUS: Active PURPOSE: this file is meant for testing. NOTES: a lot of testing goes on this file, but it is never meant to be seen by the public. */ I need to get better at documenting my code, but I try to leave comments in block sections. I act as if one day, someone is going to buy my product and I am going to sell it to them, and they will take it over and want to see clean commented code. I know if I were the buyer and saw undocumented code, it wouldn't mean anything to me and I wouldn't want to buy it. If I saw nice code, I'm more enticed because I know what's going on in that code, can hire others to help, and no one has to guess, and we don't have to break anything or have any type of learning code. Take Twitter for example... built on multiple levels of code, starting on Ruby On Rails, then evolved to Scala and Java with some Javascript in the mix. Re-writing code into another language is no easy task for any programmer, especially undocumented code. If the code, however, is documented, than instead of having to decipher what code is doing, it's all the more easier to read and re-write code into a new language if it is heavily documented. Hence... Twitter being bought by Elon Musk for $44 billion. Although Elon Musk didn't technically buy Twitter because it has amazing well documented code, Twitter itself became a large corporation based on its own ability to somewhat organize, specifically its hashtags. Elon is not an active programmer and pays people to write code, but at some point in his life, he was a programmer who knew C and probably understands a lot of different code, as he oversees many projects involving code that performs different functions, specifically for Tesla. So when writing code, always pretend that someone else is going to be looking over it and even better if you pretend they have no idea how to read code. With proper documentation, however, they won't need to understand how to read code. |