Comments on: The Literacy of Programs http://www.nagarro.com/blog/the-literacy-of-programs/ Nagarro blog: software development, design, architecture and usability Fri, 30 Jul 2010 13:51:47 -0700 http://wordpress.org/?v=2.8.4 hourly 1 By: Amit Jain http://www.nagarro.com/blog/the-literacy-of-programs/comment-page-1/#comment-144 Amit Jain Sat, 15 Dec 2007 22:28:59 +0000 http://blogs.nagarro.net/kayser/the-literacy-of-programs/#comment-144 Vaibhav, Most of the time the useless comments are produced when code commenting is done after the coding is complete. A developer does this just to satify himself that he is following good coding practices. It is a good practice to write comments at the same time (or earlier than) you write your code. Commenting while you code forces you to make sure your logic "sounds right". Plus, your comments are going to be more accurate when the understanding of what's going on behind-the-scenes is fresh in your mind. Vaibhav,
Most of the time the useless comments are produced when code commenting is done after the coding is complete. A developer does this just to satify himself that he is following good coding practices.

It is a good practice to write comments at the same time (or earlier than) you write your code.

Commenting while you code forces you to make sure your logic “sounds right”. Plus, your comments are going to be more accurate when the understanding of what’s going on behind-the-scenes is fresh in your mind.

]]> By: Bill Kayser http://www.nagarro.com/blog/the-literacy-of-programs/comment-page-1/#comment-143 Bill Kayser Tue, 02 Oct 2007 05:59:43 +0000 http://blogs.nagarro.net/kayser/the-literacy-of-programs/#comment-143 Hi Vaibhav. Yes, that's me during my visit to Delhi a couple of years ago. Manas Fuloria gave me the full tour including the campus of IIT, which I'd heard so much about. I agree with your point about useless comments. Yesterday I came across a class called "LinkAdapter" which stated plainly in it's class comment "The methods for the LinkAdapter class." It's hard to imagine a less helpful class comment, and this was from a very competent developer! I think people are sometimes conflicted between leaving useless comments and leaving nothing at all. My opinion is that when thinking about what should be commented a developer should think about their "audience". Imagine what someone would be looking for if they ever happened upon this class, method or variable. Use your experience as a programmer looking at other people's code to determine what information you would want to know. Don't focus on guidelines and the compulsion to leave comments. In the spirit of literate programming, focus on the people who will be reading them. I talk more about this in the next post. Hi Vaibhav. Yes, that’s me during my visit to Delhi a couple of years ago. Manas Fuloria gave me the full tour including the campus of IIT, which I’d heard so much about.

I agree with your point about useless comments. Yesterday I came across a class called “LinkAdapter” which stated plainly in it’s class comment “The methods for the LinkAdapter class.” It’s hard to imagine a less helpful class comment, and this was from a very competent developer! I think people are sometimes conflicted between leaving useless comments and leaving nothing at all.

My opinion is that when thinking about what should be commented a developer should think about their “audience”. Imagine what someone would be looking for if they ever happened upon this class, method or variable. Use your experience as a programmer looking at other people’s code to determine what information you would want to know. Don’t focus on guidelines and the compulsion to leave comments. In the spirit of literate programming, focus on the people who will be reading them.

I talk more about this in the next post.

]]> By: Vaibhav http://www.nagarro.com/blog/the-literacy-of-programs/comment-page-1/#comment-142 Vaibhav Mon, 01 Oct 2007 13:25:40 +0000 http://blogs.nagarro.net/kayser/the-literacy-of-programs/#comment-142 Hmm... just noticed by Ajay, the picture has the IIT Delhi Convocation hall in the background... Interesting... what's the story behind that? Hmm… just noticed by Ajay, the picture has the IIT Delhi Convocation hall in the background… Interesting… what’s the story behind that?

]]> By: Vaibhav http://www.nagarro.com/blog/the-literacy-of-programs/comment-page-1/#comment-141 Vaibhav Sun, 30 Sep 2007 11:16:33 +0000 http://blogs.nagarro.net/kayser/the-literacy-of-programs/#comment-141 Hello Bill, While I can't help but agree that code should be written so that it can be 'read'; one problem that I often come across (and not just in Nagarro, but in a lot of open source code that I get to read) is that there are often times useless comments. These comments actually break the flow of a piece of code you are trying to read. And the main reason for these comments is that programmers are pummeled again and again by people telling them that comments are critical. Like you very rightly said, a program is a piece of literature; does one need to be a good writer to judge correctly which comments are needed and which are simply in the way? Or is this something that can be taught/learned? Cheers. Hello Bill,

While I can’t help but agree that code should be written so that it can be ‘read’; one problem that I often come across (and not just in Nagarro, but in a lot of open source code that I get to read) is that there are often times useless comments.

These comments actually break the flow of a piece of code you are trying to read. And the main reason for these comments is that programmers are pummeled again and again by people telling them that comments are critical.

Like you very rightly said, a program is a piece of literature; does one need to be a good writer to judge correctly which comments are needed and which are simply in the way? Or is this something that can be taught/learned?

Cheers.

]]>