Subscribe to CodeTalk        RSS Feed
-----

Readable Code vs. Comments

Icon 4 Comments
Many of the beginner (well, and not beginner) developers as well are sometimes wondering - what is more important - readable code or comments? Now, I would like to warn you - the opinion expressed in this blog post is my own, therefore it might or might not be the same as yours.

I do think that readable code that can be esily understood and the logic analyzed without much reading is an asset for any application. Especially, this applies to large chunks of code. For example, let's take a look at this code:

			// Initialize a SQL connection that is null
			SqlConnection c = null;
			// Create the actual SQL connection
			c = new SqlConnection("Data Source=server;Initial Catalog=init;User Id=admin;Password=asdfh4CHsjO3;");
			// Open SQL connection.
			c.Open();

			// Build the SQL query
			string sc = string.Format("SELECT [F1] FROM [F2].[CAT].[SMTHNGELSE] WHERE CN='{0}'", TextBox1.Text);
			
			// Create a new SQL command
			SqlCommand c2 = new SqlCommand(sc, c);



This is some generic C# code designed to connect to a database. As you see, the imaginary developer who wrote this code used a lot of comments. But, most of them are absolutely useless. For example, why would anyone need to tell the person who is reading the code that SqlConnection c = null; will // Initialize a SQL connection that is null. This comment, however, is cluttering the overall code. Also, the variable names are a bit meaningless, considering the fact the code is going to be reused over and over again.

Now, imagine the situation where there are no comments in the code and you see this:

c.Open();



What exactly is being opened? Nobody knows and chances are that even the initial developer will forget what is the purpose of that mystical c in the algorithm.

Now, let's take a look at another piece of code (actually, it is the same as above, only modified a bit):

			SqlConnection sqlConnection = null;
			sqlConnection = new SqlConnection("Data Source=server;Initial Catalog=init;User Id=admin;Password=asdfh4CHsjO3;");
			sqlConnection.Open();

			string sqlQuery = string.Format("SELECT [F1] FROM [F2].[CAT].[SMTHNGELSE] WHERE CN='{0}'", TextBox1.Text);

			SqlCommand sqlCommand = new SqlCommand(sqlQuery, sqlConnection);



As you see - no comments used at all, but you can still see the and understand the overall code logic, because the variables have very descriptive names, and now, if you see sqlConnection.Open();, you are quite positive that a SQL connection is being opened.

Of course, I don't say that comments are not needed. It would be great to introduce this in before the actual code:

// A method that connects to the database
// that contains the users that are allowed to 
// access the backend of the system



But comments should, in my opninion, be reduced to the minimum and replaced with extremely readable code. This is not hard, once you start paying more attention to the variable/method/function etc. naming conventions that will allow you to dive into the code without reading additional pages of comments.

4 Comments On This Entry

Page 1 of 1

KeyboardKowboy Icon

30 October 2009 - 10:25 AM
I couldn't agree more with your post. Having to search backward through code to figure out what object 'c' actually is, is terribly inefficient and makes code maintenance that much more difficult. A descriptive block comment before a class or method header should fill in any gaps that could not be deduced by the code within. If using 'meaningful' variable and class names, each line of code does not need to be commented on, and makes reading the code flow more logically.
0

tivrfoa Icon

30 October 2009 - 10:41 AM
I agree. :D :^:
0

fremgenc Icon

30 October 2009 - 04:57 PM
Agree 100%. only if professors would become modern and understand this concept too.
0

cfoley Icon

30 October 2009 - 06:46 PM
I would go one more step and say that the method name should be descriptive enough not to need comments too. Obviously there are exceptions but it should be something to strive for.

In credit to lecturers, they do have to make sure you can document code as well as being able to write it.
0
Page 1 of 1

About this place

Who am I?

I am Dennis Delimarsky, and I am a software developer. Although I am still learning a lot of things, I already have some experience developing client applications. I am working with C#. I totally enjoy coding, but I am also passionate about reading and technical writing. And by the way, I am also an administrator here on Dream.In.Code.

What is this blog about?

This blog is about software development and some tools that I make.

How can I talk to the author?

Just go to http://ohai.im/dennis to find out about my web presence. Or just send me an email: codetalk@live.com

Search My Blog

July 2014

S M T W T F S
  12345
6789101112
13141516171819
20212223242526
272829 30 31  

0 user(s) viewing

0 Guests
0 member(s)
0 anonymous member(s)