20 Nov 08 Commenting source code is only for the weak

1
2
3
4
5
6
7
8
9
10

public String write(StringBuilder fle, StringBuffer con) {
  File f = new File(fle.toString());
  FileReader fr = new FileReader(f);
  BufferedReader br = new BufferedReader(fr);
  String lin;
  while((lin=br.readLine())!=null){
    con.append(lin).append("\n");
  }
  return con.toString();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

public String read(StringBuilder fle, StringBuffer con) {
  //Opens the file with the name container in the fle parameter
  File f = new File(fle.toString());
  //Create a file reader, then a buffered reader to make our work easier
  FileReader fr = new FileReader(f);
  BufferedReader br = new BufferedReader(fr);
  String lin;
  //Read each line of the file until it is null
  while((lin=br.readLine())!=null){
    //Put the content read into the buffer pointed by the parameter "con"
    con.append(lin).append("\n");
  }
  //The caller already have the content, because he created the buffer, but I'll return the string anyway
  return con.toString();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

public String readFileContents(File fileToRead) {
  boolean canReadFile = fileToRead.exists();
  if(!canReadFile)
    return "";
  StringBuilder buffer = new StringBuilder();
  BufferedReader readerForFile = openBufferedReaderForFile(fileToRead);
  readFileContetIntoBuffer(buffer,readerForFile);
  closeFileReader(readerForFile);
  return buffer.toString();
}
private  BufferedReader openBufferedReaderForFile(File fileToRead){
  return new BufferedReader(new FileReader(fileToRead));
}
private void readFileContetIntoBuffer(buffer,readerForFile){
  String line;
  while((line=readerForFile.readLine())!=null){
    buffer.append(line).append("\n");
  }
}
private void closeFileReader(readerForFile){
  readerForFile.close();
}

1
2
3
4
5

public String write(StringBuilder fle, StringBuffer con) {
  File f = new File(fle.toString()); FileReader fr = new FileReader(f);  BufferedReader br = new BufferedReader(fr);
String lin; while((lin=br.readLine())!=null){  con.append(lin).append("\n");  }
  return con.toString();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

package blog;
 
import java.io.BufferedReader;
import java.io.File;
import java.io.FileNotFoundException;
import java.io.FileReader;
import java.io.FileWriter;
import java.io.IOException;
 
public class VeryBadlyNamedFile {
	private static final char[] asdfg = new char[] {'I', ' ', 'c', 'a', 'n', ' ', 'd', 'o', ' ', 'v', 'e', 'r', 'y', ' ', 'u', 'g', 'l', 'y', ' ', 'c', 'o', 'd', 'e'};
	private String an;
	private BufferedReader rfsdw;
	private FileReader temp;
 
	public VeryBadlyNamedFile(String an, BufferedReader rfsdw, FileReader temp) {
		super();
		this.an = an;
		this.rfsdw = rfsdw;
		this.temp = temp;
	}
 
	public void doIt() throws IOException {
		ctfiidne();
		startDoing();
		try {
			canIDoAnyThing();
		} catch (RuntimeException yicdet) {
			nowReallyDoIt();
		}
	}
 
	private void nowReallyDoIt() {
		firstDoTheOtherThing();
		reallyDoItInternal();
	}
 
	private void firstDoTheOtherThing() {
		rfsdw = new BufferedReader(temp);
	}
 
	private void reallyDoItInternal() {
		while (true) {
			try {
				imDoingIt();
			} catch (Exception e) {
				break;
			}
		}
	}
 
	private void imDoingIt() throws Exception {
		String s = rfsdw.readLine();
		if (s == null)
			throw new Exception("hahaha, I bet you did not understood the code");
		System.out.println(s);
	}
 
	private void ctfiidne() throws IOException {
		File a = new File(an);
		if (!a.exists()) {
			FileWriter wrfedsd = new FileWriter(a);
			wrfedsd.write(asdfg);
			wrfedsd.close();
		}
	}
 
	private void canIDoAnyThing() {
		if (new File(an).exists() && new File(an).canRead() && new File(an).canWrite())
			throw new RuntimeException();
	}
 
	private void startDoing() throws FileNotFoundException {
		File f = new File(an);
		temp = new FileReader(f);
	}
}

1
2
3
4
5
6
7
8
9

package blog;
 
import java.io.IOException;
 
public class Main {
	public static void main(String[] args) throws IOException {
		new VeryBadlyNamedFile("c:\\anyFile.any",null,null).doIt();
	}
}

Reader's Comments

1. Javier | 20 Nov 2008 12:19 pm

   I think it’s a good practice, but sometimes there are limitations, by the way I don’t be clear with the last phrase, what it means?

   Reply to this comment
2. DevTopics | 20 Nov 2008 12:36 pm

   Good article. I agree that it’s important to use meaningful variable names and give each instruction its own line so that others can understand what your code is doing simply by reading the code.

   Where comments come in most handy is not explaining WHAT you are doing, but explaining WHY you are doing it. Often the WHY cannot be deduced simply by reading the code, and in these cases comments are essential.

   Reply to this comment
3. Urubatan | 20 Nov 2008 12:40 pm

   Javier, sorry for my bad english, I need to study more.
   The phrase is corrected now (I think it is )

   Just pray for god’s help, and beg him that the next one to read the crap you are creating is not a serial killer that knows where you live.

   DevTopics, I totally agree with you, but I think that people need to learn not to comment first, and only then, they can learn to comment right

   Reply to this comment
4. Russ | 20 Nov 2008 2:02 pm

   Oh great, another blogger that doesn’t understand the how/why distinction. Here’s a code snippet:

   request.Description = description.substring(0, 30);

   That’s easy to read, right? Easy to see what’s going on, no need to add a comment, right?

   Then you get a change request to truncate the description at 40 characters because some information is being lost. How do you know that won’t be a breaking change without knowing WHY the current truncation is at 30?

   Now imagine there’s a simple one-line comment:

   // 3rd-party binary wire protocol has 30-char limit

   Aha! Now thanks to the consideration of your predecessors, you have the information you need, saving you hours of traipsing through layers of code and interfaces to 3rd-party systems.

   Comments are for explaining why things are done, not for restating how to do something.

   Reply to this comment
5. Urubatan | 20 Nov 2008 2:47 pm

   Russ, I just agreed with “DevTopics” exactly on what you have wrote here.
   I agree that commenting WHY you are doing something is good, this post is about when the comments are telling HOW you are doing something. Of course it is being done in a very aggressive way, but I totally agree with you.

   Reply to this comment
6. Greg M | 20 Nov 2008 11:56 pm

   @Russ:

   No, no, no.

   The _first_ thing you should do is fix the code.

   Define 30 as a constant with a meaningful name like “XProtocolCharLim”.

   Now you can start thinking about whether an additional comment is justified.

   Reply to this comment
7. Jörg | 21 Nov 2008 7:03 am

   Oh, man! This post seems to miss the point a bit.

   Comments are not for describing “what” happens in a particular piece of code, but about “why” it’s coded the way it is.

   Of course, if you begin something from scratch, it’s up to you to design it in a way, that javadoc comments suffice to describe the “why” in most of the cases.

   In reality, it happens that you get assigned to work on less optimal designed software, where you are happy if some comments describing the “why” exist, or where you are not given the time to refactor enough and hence have no better choice as to resort to comments when improving code readability on the fly…

   Reply to this comment
8. lonestranger | 21 Nov 2008 10:38 am

   PS4: You should learn ENGLISH!!!!!

   Reply to this comment
9. Brett | 21 Nov 2008 10:47 am

   I agree with only using appropriate commenting. I usually assume that if someone is reading my code, they can understand what the code is doing in general if they have an idea of what it is supposed to do. So I usually simply have comments for larger sections of code, or for functions, that say something like “Read the file in and store it in the stringBuffer con”. But I would agree that commenting every other line is a waste of your time, I think a comment like “//Open the file” is (almost) never necessary.

   Reply to this comment
10. Urubatan | 21 Nov 2008 12:24 pm

    Jörg, this post is not missing the point, it is talking about how comments are used by many programmers on the market.
    And I’m stating that these programmers, that use comments to describe what the code do, are losers.

    Reply to this comment
11. Urubatan | 21 Nov 2008 12:26 pm

    Brett, if you have this kind of comment, you need to read the post again, and stop commenting.
    If the comment says what the code do (like in your example “Read the file in and store it in the stringBuffer con”), the comment is wrong, it should not say what do code do. Why it is done is OK.
    Of course if this is a javadoc comment, it is documentation for some one without access to the source code, then it is OK.

    Reply to this comment
12. Urubatan | 21 Nov 2008 12:35 pm

    lonestranger,
    I’m studying,
    And I’ll thank you if you are kind enough to point my errors.

    Reply to this comment
13. Javier | 21 Nov 2008 1:53 pm

    Please people, what’s going on!, is this a blog for learn something? or some kind of “I’m better than you!” blog, a little of respect for our points of view is required, just my humble opinion.

    Reply to this comment
14. aaron | 26 Nov 2008 5:30 pm

    While I can sort of agree with your overall message, this was not a very good example. Looking at the first code block, it was very apparent to me what that code did (aside from naming the function/method “write;” what is being written?). I do agree that the comments in the second example are completely overboard. However, your third block is just ridiculous. An operation as simple as reading data from a file and into a buffer is not complicated enough to warrant being broken up into 4 separate functions (unless the specific app/project you are working on has use for those individual functions in another context).

    Over-commenting is unnecessary, certainly, but restructuring your code and making it needlessly complicated when some comments will suffice is even worse.

    Reply to this comment