Have you ever been reviewing code and come across a comment that you deemed was unnecessary? Commenting your code is meant to improve the readability of your code and make it more understandable to someone other than the original developer.
I have identified 5 types of comments that really annoy me and the types of programmers who make them. I hope after reading this you won’t be one who falls into one of these categories. As a challenge, you can try to match up these comment programmers with the 5 types of programmers.
1. The Proud Programmer
{
static void Main(string[] args)
{
string message = "Hello World!"; // 07/24/2010 Bob
Console.WriteLine(message); // 07/24/2010 Bob
message = "I am so proud of this code!"; // 07/24/2010 Bob
Console.WriteLine(message); // 07/24/2010 Bob
}
}
This programmer is so proud of his code that he feels the need to tag every line of code with his initials. Implementing a version control system (VCS) allows for accountability in code changes, but at first glance it won’t be so obvious who is responsible.
2. The Obsolete Programmer
{
static void Main(string[] args)
{
/* This block of code is no longer needed
* because we found out that Y2K was a hoax
* and our systems did not roll over to 1/1/1900 */
//DateTime today = DateTime.Today;
//if (today == new DateTime(1900, 1, 1))
//{
// today = today.AddYears(100);
// string message = "The date has been fixed for Y2K.";
// Console.WriteLine(message);
//}
}
}
If a piece of code is no longer used (i.e. Obsolete), delete it – don’t clutter your working code with several lines of unnecessary comments. Besides if you ever need to replicate this deleted code you have a version control system, so you can recover the code from an earlier revision.
3. The Obvious Programmer
{
static void Main(string[] args)
{
/* This is a for loop that prints the
* words "I Rule!" to the console screen
* 1 million times, each on its own line. It
* accomplishes this by starting at 0 and
* incrementing by 1. If the value of the
* counter equals 1 million the for loop
* stops executing.*/
for (int i = 0; i < 1000000; i++)
{
Console.WriteLine("I Rule!");
}
}
}
We all know how basic programming logic works – this is not “Introduction to Programming.” You don’t need to waste time explaining how the obvious works, and we’re glad you can explain how your code functions – but it’s a waste of space.
4. The Life Story Programmer
{
static void Main(string[] args)
{
/* I discussed with Jim from Sales over coffee
* at the Starbucks on main street one day and he
* told me that Sales Reps receive commission
* based upon the following structure.
* Friday: 25%
* Wednesday: 15%
* All Other Days: 5%
* Did I mention that I ordered the Caramel Latte with
* a double shot of Espresso?
*/
double price = 5.00;
double commissionRate;
double commission;
if (DateTime.Today.DayOfWeek == DayOfWeek.Friday)
{
commissionRate = .25;
}
else if (DateTime.Today.DayOfWeek == DayOfWeek.Wednesday)
{
commissionRate = .15;
}
else
{
commissionRate = .05;
}
commission = price * commissionRate;
}
}
If you have to mention requirements in your comments, don’t mention people’s names. Jim from sales probably moved on from the company and most likely the programmers reading this won’t know who he is. Not to mention the fact that it everything else in the comment is irrelevant.
5. The Someday Programmer
{
static void Main(string[] args)
{
//TODO: I need to fix this someday – 07/24/1995 Bob
/* I know this error message is hard coded and
* I am relying on a Contains function, but
* someday I will make this code print a
* meaningful error message and exit gracefully.
* I just don’t have the time right now.
*/
string message = "An error has occurred";
if(message.Contains("error"))
{
throw new Exception(message);
}
}
}
This type of comment is sort of a catch-all it combines all the other types. The TODO comment can be very useful when you are in the initial development stages of your project, but if this appears several years later in your production code – it can spell problems. If something needs to be fixed, fix it now and do not put it off until later.
If you are one who makes these types of comments or would like to learn best practices in comment usage, I recommend reading a book like Code Complete by Steve McConnell. This is one of the books that I recommend all programmers should own.
Or Perhaps you can learn how to stop commenting your code altogether.
Do you see any other unnecessary or annoying comments in your code? Please feel free to share.
How To View Inception Through Code
If you have not seen Inception yet, I highly recommend doing so before reading this post.
Inception combines the best elements of movies in the Simulism genre; such as Dark City, eXistenZ, The Thirteenth Floor and The Maxtrix Trilogy; and creates an original, thought provoking film.
Watching the film from the standpoint of a programmer, I could not help seeing the similarities between the plot devices and basic programming concepts.
The Kick
The Kick is the concept they use in the movie to return to a dream level above the existing one. For example, if you perceive that you are falling in a dream, you have a tendency to wake up.
The Kick can be portrayed in programming in several different ways:
Recursion
{
kick = CheckForKick();
if(kick) return true;
return Dream();
}
* CheckForKick() implementation has been omitted.
In this recursion example, each call to function Dream() will call another sub-Dream – until the CheckForKick() function returns true, which can occur however many levels deep.
Exception Bubble
{
try
{
try
{
try
{
throw new DreamException("Receive Kick");
}
catch(DreamException dx)
{
throw dx;
}
}
catch(DreamException dx)
{
throw dx;
}
}
catch(DreamException dx)
{
// Handle Kick thrown 3 levels deep.
Console.WriteLine(dx.Message);
}
}
In this Exception example, an exception is thrown within a nested try block. Rather than handling the exception at that level, it’s bubbled up until is (hopefully) handled gracefully.
Stack
This can best be represented by the following infographic, which I reconstructed to be a stack. Here is the original source.
A stack is one of the most fundamental data structures in computing. A stack operates in the following: items are added in a First-In, Last-Out (FIFO) manner. They are added via being “Pushed” onto the stack and removed via being “popped” from the Stack.
In the movie, each sub-dream is pushed onto the stack starting with reality. Our characters cannot return to a different dream level by popping the dream above off the stack.
Sedation
They use Sedation in the movie to prevent the dreamers from waking up any means other than “falling” on all dream levels above the first. At the first dream level, the only way to wake up is for the machine’s time to elapse.
Sedation in the movie can be explained through the use of Threading.
Threading
{
Machine mach = new Machine();
Sedation sed = new Sedation();
Thread machineThread = new Thread(new ThreadStart(mach.Start());
Thread sedationThread = new Thread(new ThreadStart(sed.Sedate());
try
{
sedationThread.Start();
machineThread.Start();
sedationThread.Join();
machineThread.Join();
ReturnToReality();
}
catch(Exception ex)
{
// Limbo ???
}
}
* Machine implementation omitted. Sedation implementation below.
In this example, you can think of the sedation and starting the “dream machine” as being two separate threads – both induce unconsciousness, but in different ways.
The sedation occurs first as indicated by the sedationThread.Start(), followed by the machine start machineThread.Start(). The Sedation.Sedate() implementation may look like the following:
{
Thread.Sleep(36000000); // 10 Hours
}
By calling join on the threads, the ReturnToReality() function will not get called until both the sedation wears off or the machine time elapses.
Limbo
Limbo is defined in the movie has a mental state where your mind doesn’t know if you are in reality or not. The only way out is to realize that Limbo is not reality.
I already hinted at how Limbo could be represented in code in the previous example – if there is an exception (i.e. death) during the running of the threads that does not allow them to complete. Also, Limbo could also be represented by the following:
Infinite Loop or Infinite Recursion
{
CreateBuildings();
CreateFromMemories();
QuestionReality();
}
Most of the time that we are programming and find ourselves in an infinite loop, we are not aware of it until we start to question:
Fortunately in programming there are ways to identify that we are in an infinite loop state.
If you are not aware of these conditions, you will stay there until your program runs out of memory or crashes (dies) or you realize you are in a loop (meet a condition) – by calling the QuestionReality() function.
Architect
The last item I will mention is the role of Architect. In the movie, Ariadne (Ellen Page) is responsible for creating the dreamscapes. This shares similarities with Software Architecture. As a software architect you responsible for knowing the systems (the main characters in movie) that you work with and to create the best solutions (e.g. Never Ending Staircase) to new problems that need to be solved (Inception). Being able to see the world around you as objects with state and behavior is a useful skill for both understanding Object Oriented Design/Programming; and as a Software Architect.
I was surprised how many people shared similar thoughts with comparing the movie with programming. If you enjoyed my post, please read their perspectives: