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:

Small Basic Comments

 

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 http://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 (5)

  1. Durval Ramos says:

    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.

  2. Awesome, thanks Durval!

    I'll incorporate this in!

  3. 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.aspx

Skip to main content