Since you’re reading this blog, I assume you like to read, as does every developer I’ve ever met. This is why we’re going to discuss naming conventions and comments and how to effectively use them in your Code. I’m of the opinion that we should cover this topic now, we just went over variables and how to define them, lets exercise some best practices and name them correctly. This will also help us when naming methods and other parts of our code as we continue to lay the foundation of coding skills.

First lets look at some bad code and walk through whats wrong with it:

Problem 1: Lets look at the two integer declarations (myAwesomeValueOne and myAwesomeValueTwo). They don’t describe what the value is and they don’t let the reader know what they’re used for.

Problem 2:  Looking at the method johnnysMethod, we can tell it takes in two integer arguments, however we have no idea what the method is doing. Naming the method johnnysMethod tells us nothing other than keep reading if you want to figure this shit out.

Problem 3: johnnysMethod should be capitalized as its standard practice for methods or functions.

How do we solve this bad code and help johnny and his methods of madness? Digging through the code further we can deduce that johnnysMethod is taking in two integer values, adding them together and outputting the sum into the console. Lets start by renaming his variables to valueToAddOne and valueToAddTwo. This tells us there are two values and they’re being added or calculated in some way. This helps us understand more of whats going on.

Next lets rename johnnysMethod to SumTwoNumbers(). It summaries what the method is doing, its simple and elegant. Your future self will thank you for providing meaningful names like this. This name also meets our naming convention requirements by using compound words and capitalizing letters where appropriate.

Heres how the new code looks:

Whats great about this example is when you’re reading the code you can stop at the method call SumTwoNumbers and know exactly what this program is doing. If you need to move onto something else you can because the entire program is easy to read and tells a story. Much like writing or reading a book, crafting meaningful and clean code is an art form.

Now lets talk about Code Comments, what are they?, how are they used?, do I need them?

What are they?

Code comments allow you to write text inside your code that the compiler will ignore, its a way of injecting notes or todo items or an explanation about what that code does. They can be included anywhere in your code and will have no effect on the program and how its compiled.

How are they used?

Single line comments are denoted by a double forward slash

// this is a single line comment

 
/* this is a multiline line comment 
   notice everything between the slash stars are commented.
*/ 

 
/// XML tags can be displayed in code comments like this 

Do I need them?

Part of me says no, never ever use code comments. Why you ask? well if you read Clean Code by Robert Martin, he talks about good code, he states that it doesn’t need comments as it reads well on its own. When something is commented its either doing too much, or not properly named, or never got refactored.

I use code comments, I use it for debugging, taking chunks of code out of a class or file to work through tests and other procedures. I think this is the right approach and I’m actively trying to keep comments out of my future code, spend time on your naming conventions and getting it right the first time. Save comments for debugging.

Happy Coding,

Corey