Good Comments and Bad Ones
This is Day 5 of 30 Days of Small Basic Part 1.
Different languages use different methods to block off code comments.
Here are three different syntaxes of code commenting:
<!-- Code Commenting to give a section title -->
// Code commenting, usually after a statement on that same line
' Code commenting, usually after a statement on that same line
Small Basic uses the single quotation (') commenting syntax. Read more here:
In programming, it's a good habit to properly comment your code!
But, you could comment too much or use comments in a way that actually makes your code harder to read and understand!
This blog post takes a look at the examples of both good comments and bad ones.
Good Comments
' Welcome.sb
You might want to include your source code file name at the top of your source code.
' This program calculates the area of a triangle
It's a great idea to comment an explanation of your program at the top of your source code!
' I'm using the Newton-Raphson method
This helps explain your methods, and your fellow coder can look them up to learn about them!
' This next If Else statement selects the correct menu option
It's good to use comments to break apart code blocks and introduce them!
Y0 = 7 * scale ' Goes seven units down
When your code gets a little tricky, you should explain what each line does, so that someone can pick it up and follow along with your steps! This line might make sense in context, but if it doesn't, then you'll need to explain it even more!
' TO DO: Add the calculations
While it's not best to have a lot of these (and not a lot of actual functionality), it still helps you find what's missing and what you still need to do (versus leaving it blank), and it tells your fellow programmer what your intentions are (or were). Likewise, it's better to write up your ideas while they're fresh in your mind. That way, when you get to that section, you'll remember what you wanted to do! In fact, you might want to start by writing a lot of lines of commented code that outline your program. Then you go in and replace the commented lines with the sections!
Bad Comments
Here are some examples of code comments that you should avoid...
' This code is hard to use, so you need to replace three calls in order to customize it...
Let's stop right there! If any code is hard to use, and you know it, then it's time to stop explaining it and time to start re-writing it! I know, sometimes it's easier not to, but as you make the code more functional, you'll be teaching yourself a lot for the future as well!
' Because the moronic users sometimes enter negative numbers
Please be polite! You never know who's going to read your code and take offense at it!
' This fixes the problem created by the monkeys who developed the source code
Again, be polite. One day those "monkeys" might be interviewing you for a job!
' This reminds me of a joke...
That's a little unprofessional to drop a joke in your comments! If you really need to do this, then leave them out and write a book or blog post instead! =^)
' My Employee ID: 900707293
Personal information might be helpful to you, but you never know who's going to get your code! It's better to put that information in a personal OneNote or other place you store your info.
' Here's what the program does. First, it... After that, it's going to... And then, it... It's going to call a subroutine that...
You don't need to write an essay that explains your program. It's better to cut this up for each section, and use fewer words to explain them.
Go to https://blogs.msdn.com/SmallBasic to download Small Basic for free and learn all about it!
Have a great day!
- User Ed
This is Day 5 of 30 Days of Small Basic Part 1.
Comments
Anonymous
August 03, 2014
Hi Ed, I believe that a good comment should be simple and clean, especially should be written as "a message to yourself in the future". Even if you (developer) think that never will change this source code again. A Best Practice is also declare variables and objects with short names, but clarifying what is It's purpose. It's important to avoid generic names, e.g.: "X" and "Y" variable.Anonymous
August 05, 2014
Awesome, thanks Durval! I'll incorporate this in!Anonymous
September 10, 2014
Thank you.Anonymous
November 29, 2014
My pleasure, Mustafa!Anonymous
January 31, 2016
Computers Today (part 1 of 6) blogs.msdn.com/.../computers-today.aspx ..... CS SPOTLIGHT: Girls in computer programming... why it matters!!! blogs.msdn.com/.../cs-spotlight-girls-in-computer-programming-why-it-matters.aspx ... Computational Thinking - Videos & Papers by Jeannette Wing blogs.msdn.com/.../computational-thinking-videos-amp-papers-by-jeannette-wing.aspxAnonymous
November 13, 2017
Hello colleagues, how is all, and what you desire to say on the topic of this piece of writing, in my view its really remarkable designed for me.