The importance of documenting code, especially if you’re a newbie!

Today I wanted to address the practice of documenting code, or putting comments in code in other words and how it has helped me.

Here’s a quick definition I pulled from Wikipedia that defines what a comment in code is and its purpose.

“In computer programming, a comment is a programmer-readable explanation or annotation in the source code of a computer program. They are added with the purpose of making the source code easier for humans to understand, and are generally ignored by compilers and interpreters.”

At this point I’m in the last half of the Bloc program, and I have to say that I’ve learned a ton since I started. Despite this, one of the challenges I have faced is how to retain that knowledge and how to retain the concepts I’ve been exposed to. New things have been flying at me everyday. It’s never a dull moment, but as a beginner, you will start noticing quickly that you don’t really understand what you’re typing into that text editor. Early on I started questioning, “how useful is this code to me, if I can’t explain what it’s doing?” The answer: “not very useful at all!”

If I’m just coping code from the screen into my editor, anyone can do that. In fact there’s a little something called ‘Copy-Paste’ for that. What I wanted was to be able to understand what I was typing and to be able to look back previous code I had typed and to be able to see what it was doing. This is where I discovered the power of commenting code. I started doing this every time I was typing a chunk of code, and when there was an explanation in the checkpoint about it, I would take that and put it in the comments. It would be way to clumsy to find something in my code, not know what it was doing, and have to comb through the Bloc curriculum to find out what the heck I did there. Instead, here was the explanation available instantaneously in case I inevitably forgot what I did and why I did it. I encourage you if you’re struggling to understand what you’re typing, don’t just ignore that! Seek to understand what you’re doing and why you’re doing it!

An interesting article I found which basically addresses a different point of view on documenting code. Interesting food for thought…

https://visualstudiomagazine.com/articles/2013/07/26/why-commenting-code-is-still-bad.aspx