Users tell you “this should be easy”, “you only have to do x”, “just another button here”? Give them the direct experience of their fallacy: **Throw the source code at them!**
Today, a colleague from the sales department, an internal user of one of our IT products, said he could not imagine that the app in question was *that* complex…
Users always only see the top of the software iceberg.
If you are an IT expert, you can plot a realistic picture of the size and complexity of an application once you know the dependencies to input data, other systems and workflows. For example, if an application needs to be kept in sync with another system or if even company boundaries are crossed, you quickly get an idea of the complexity these scenarios put on your code.
To the half knowledgeable user (the smart boys and girls), it often *just* looks like a case of “but you only have to send this XML file to them” or “call this webservice”.
I wanted to give this colleague a better understanding by making the facts more accessible in a direct, physical way. Turn the abstract concept into something real that you can experience directly. To give him an idea of “how deep the iceberg really is”…
I decided to print out the whole source code of the project, put it into a folder and throw it on his lap.
He would feel the weight of all that code we wrote during the last three years! He would look at a few of the pages and would not understand a word of what he reads, except some business realted words that he would recognize and therefore would conclude the whole thing was not a hoax.
He would understand why we, in the IT division, cannot always deliver his latest (by the way, *very good*) ideas within a day or two…
I did a quick search on Google if there was an app to turn our sourcecode into one single file for print but didn’t get lucky quickly.
I decided to spend half an hour and wrote this trivial piece of code:
public class Code2Book {
private List<string> fileTypesToPrint;
private int fileCount = 0;
private BufferedWriter writer;
public static void main(String[] args) throws IOException {
Code2Book m = new Code2Book();
File[] files = new File(args[0]).listFiles();
m.createBook(files);
}
private void createBook(File[] files) throws IOException {
fileTypesToPrint = new ArrayList<String>();
fileTypesToPrint.add("java");
fileTypesToPrint.add("groovy");
fileTypesToPrint.add("scala");
fileTypesToPrint.add("xhtml");
fileTypesToPrint.add("css");
fileTypesToPrint.add("js");
fileTypesToPrint.add("xml");
fileTypesToPrint.add("html");
if (new File("outfile.txt").exists()) {
new File("outfile.txt").delete();
}
writer = new BufferedWriter(new FileWriter("outfile.txt"));
handleLevel(files);
writer.close();
System.out.println();
System.out.println("Concatenated " + fileCount + " files.");
}
private void handleLevel(File[] files) throws IOException {
for (File file : files) {
if (file.isFile()) {
if (isFileToPrint(file.getName())) {
fileCount++;
System.out.println("file = " + file);
appendToFile(file);
}
} else if (file.isDirectory() && !file.getName().startsWith(".") && !file.getName().equals("target")) {
handleLevel(file.listFiles());
}
}
}
private void appendToFile(File file) throws IOException {
FileInputStream fis = new FileInputStream(file);
DataInputStream dis = new DataInputStream(fis);
BufferedReader br = new BufferedReader(new
InputStreamReader(dis));
String line;
writer.write(file.getName() + " - " + file.getAbsolutePath());
writer.newLine();
writer.newLine();
while ((line = br.readLine()) != null) {
if (!line.trim().equals("")) {
System.out.println(line);
writer.write(line);
writer.newLine();
}
}
writer.newLine();
dis.close();
}
private boolean isFileToPrint(String name) {
for (String s : fileTypesToPrint) {
if (name.endsWith("." + s)) {
return true;
}
}
return false;
}
}
The code snippet above simply takes the root folder of a “JDK” project, recurses through all subdirectories and concatenates all source code it finds, into one single file. Blank lines are skipped while comments aren’t.
I run it on the project the sales colleague put into question and was surprised with the result:
- 2100+ files
- 170’000+ lines of code (including comments, which we don’t do a lot :-/)
Next I was going to print it… Turned out I would have had to print out 2600+ DIN A4 pages. Given I print them double sided, this is still 1300+ physical sheets. I checked how many pages there are in a standard printing paper packet, five hundred. The “book” would be aroud 20 centimeters or about 8 inches think! You can kill a person with this kind of brick!
However, I was gonna do it and print it, no matter what, I just wanted to throw it at him… The effect would have been massive!
Then my colleagues in the IT department talked me out of it, saying boring things like “think about the environment” and so on… One guy ([Jason](http://twitter.com/retronym)) recommended to produce a [Gource](http://code.google.com/p/gource/) source code evolution movie from the GIT commits. Great idea and environmentally friendly. Everybody happy!
It does’t give you a direct idea about the **physical weight of the project, when *someone actually throws it at you***…
…but it is a joy to watch the little code jedis lasering at the file tree…
Lets see if I it works out. I will let you know…
UPDATE:
I decided not to print it but instead take a pile of around 1300 pages of plain printer paper and hand it to him. He first didn’t know what I was about. When I told him he currently held the equivalent of the projects source code, he was quite impressed, to say the least :-)
A simple idea but it totally got the point across. It made an abstract concept accessible through physical experience.
I recommend it.
Post a Comment