Urubatan’s Weblog
msgbartop
Just a little about development! Think before you write!
msgbarbottom

20 Nov 08 Commenting source code is only for the weak

Many of you will probably not agree with me, but if you read all this post, you will probably agree that commenting your source code is a sign that your code sucks. Real men write code that other people can read!
But keep in mind that I’m talking about comments that tell what the code do, and not documentation like “Javadoc”.
For example, if you ware not a Java programmer, or even being a java programmer, can you quickly tell what the code bellow do?

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();
}

Hard one? And this is a very simple code, but we can make it a little better …

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();
}

Easier, right? Now you can read the comments in the code, and understand it, but the code still crappy.

This is the kind of comment I’m talking about. Commenting your code is a sign that you are a very bad programmer (with little exceptions, in very complex algorithms that you can not break in smaller pieces of code).
When you do this, you are doing a “hack” to hide from others your own incompetence. This mean that you cannot write a clearer code. One that other programmers can read.

Here we have a little solution for the code above, a refactoring of that crappy method:

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();
}

Now if you pay attention to the method name “readFileContents”, you can already know what it does, besides that, the method code is almost legible, as you can see bellow:

if not can read file, return null
open Buffered Reader For File: fileToRead
read File Contet Into Buffer: buffer, readerForFile
close File Reader: readerForFile
return buffer.toString();

What I’m telling is that if you can read english, you can read the code, and almost every programmer in the planet knows how to read english, right?

I have even seen people doing worst things, like the snippet bellow:

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();
}

It has less lines of code than my version, but you will have a hard time trying to read a program wrote by the monster that wrote the snippet above.

Of course the example I used was a simple one, and I know that writing legible code needs practice …
But I’ll let you a proposal, not really a proposal, an exercise …

I’ll let a code example bellow, and you will try to make it more readable. And I’ll post my solution in one or two days.
If you want to post the refactored code in the comments, just use the tags <pre lang=”java” line=”1″> … </pre>

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);
	}
}

And now a “main” file to exebute the trash above.

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();
	}
}

The examples in this post are using Java, but the concept apply to any language, if you are programming and using comments to explain your code, you are a terrible programmer. 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.

PS.: I really do not think that you should not comment your code, but if your code is not understandable without the comments, you do not know how to write programs yet.

PS2.: I think I need better examples.

PS3.: the secret to write good code is to write it as if the next one that will read your code is a serial killer that knows where you live. (I do not remember who wrote this sentence in the first place, I’ll research and post it here)

If you enjoyed this post, make sure you subscribe to my RSS feed!

Tags: , ,

Filed in java, productivity, rails with 15 Comments

20 Dec 07 Tips for the SCEA 5 Beta exam – part 3

Yesterday I finished the third and last part of the SCEA 5 Beta exam …
The only bad news is that the results will only be available after February 15th :(

One good thing, is that this is the only certification I took until now that worth something!
The first objective test is very easy if you already work with system architecture and know at least a little about each Java EE technology …
The second part is not hard too, you have to design a system for a given problem, the only hard part on the Beta was to do it within 2 weeks, and for me those ware two full weeks, I was moving from one city to another, and already had some other things to do, at the end I could work on the project for only 20 hours (it was specified for between 40 and 60 hours), I hope I did it well enough …

The third and last part, is basically to prove that it was really you that created the project …
Before going to the test place, make sure you read all that you send with your project, write down every decision you make and why you made it, this two little tips will help you a lot in the final part of this certification …

Well, not I’ll wait untill February 15th to know if I cleared the exam :D
Good luck for me and for every one that read to here :D

If you enjoyed this post, make sure you subscribe to my RSS feed!

Tags: , , , ,

Filed in java with 2 Comments
sidebartop

Recommend this blog

Recommend Me
Add to Technorati Favorites
sidebarbottom
sidebartop

Sponsored links

sidebarbottom
sidebartop

Recent Posts

sidebarbottom
sidebartop

Tags

sidebarbottom
sidebartop

Recent Comments

sidebarbottom
sidebartop

Cool Software

Basecamp Highrise Backpack
sidebarbottom
sidebartop

Time machine

sidebarbottom
sidebartop

License

Creative Commons License
Blog do Urubatan by Rodrigo Urubatan Ferreira Jardim is licensed under a Creative Commons Attribution-Share Alike 2.5 Brazil License.
Permissions beyond the scope of this license may be available at http://www.urubatan.info/contact/.
sidebarbottom
© Urubatan’s Weblog / Design: Smashing Wordpress Themes