|
> Insights that can only be derived through higher-order analysis are left to the intuition and synthesis powers of the learner As a robotics nerd with a highly technical background and knowledge in Visual Basic, Python, C++ and the Arduino-flavored variant of it, I highly disagree. I feel that those who say "code should document itself" miss the fact that, at least to a "novice" there's a lot of stuff that doesn't self-reveal its purpose. For instance, the Arduino extensions to C++ are very confusing at times, and the editor doesn't even have tooltips or the like. Even after switching to Visual Studio Code and its Arduino extension (which is great, BTW- thanks to anyone that's reading this who helped out on either project) there's still a lot I don't natively understand. I personally don't document all my code, but like how third-graders don't natively understand the Pythagorean Theorem, but can be taught it, I put everything that I didn't understand right off the bat in my notes or my engineering notebook, and / or in my code, often with a StackExchange link that has a more complete explanation. I find it somewhat offensive that even in products targeted towards "Makers" where this might be their first programming project, the documentation is sub-par and StackExchange is better, even in just pulling out some code that's already there somewhere else. [0] Physics doesn't speak English, you translate it in your head. Eventually. Code is a different language, that like English with its weird (I before E, except after C, most of the time) rules, needs explanation from time to time. We're not all college graduates with a BS in Comp Sci, and I feel like movements like these make programming more elite and off-putting to beginners. [0] https://electronics.stackexchange.com/questions/67087/analog... |