I started out this web 2 series with a rather general introduction here. However I have to admit that I wasn’t very specific, nor pragmatic in this blog. This has got to change right here because for me web 2, and especially wikis, is all about a pragmatic approach:

The ability to document necessary and important information and allowing for as many people as possible to read, edit and give feedback upon this information.

This is collaboration. This is wikis.

Unfortunately, documentation often has a poor sound to it these days with the agile winds blowing in the software industry. Don’t get me wrong, these agile winds are definitely good and I think we are on the correct path here. However, I think there still is a need for some documentation. Only, the documentation has to be as agile as the process of developing the code itself. This is where wikis come into the picture as a better documentation persistence tool.

The traditional documentation approach is by using a file-based storage for content. Usually the tool is some version of Microsoft Word which is probably what 90% of what people are using. The editing functionality in this tool is excellent. However, I do recognize a number of weakness as I will note down as I go along comparing file based storage with wikis.

Published, not stored!

A wiki is always reached via a web browser. Therefore, when writing content on a wiki, it is naturally published on a web server for all authorized users to see. This is a great strength since everyone these days are used to a web browser for localizing information.

File based documentation is however often a pain to even locate on a company. Often, such files are placed on a file server somewhere in some obscure directory. Often I find that there are several of these directories too which makes the wanted document even more difficult to find.

However, an interesting approach is Microsoft Collaboration platform SharePoint. Here SharePoint is responsible alone for knowing the actual physical storage of the file and files are only provided as links to the users for download or viewing. This is a lot better approach. Unfortunately, due to licensing costs, a SharePoint solution is often not doable for smaller companies.

Refactoring structure

As when programming code it is difficult to know the exact structure before work has begun. Requirements (input data) may change or you may get new ideas as you work with the code/document. When creating a file based document, the scope for it has to be carefully considered. The information that is out of scope has to be placed in another document which instead is referred to. I find that file based documentation does not leave you much choice for actually editing the scope of the document once you have started working on it. Wikis on the other hand allow you to quite easily refactor the structure and scope as you go along. This since the actual document you are writing is split into several pages reachable via links. It is quite easy to create a new page in a wiki and link to this page which makes refactoring extremly easy. Referencing other file documents in a file document is a much harder this to do. At best you may link to a referenced file document, but this document still probably is a huge source of information so it will still take you quite some time to locate the desired information within this referrenced document.

This refactoring mechanism is one of the largest benefits with a wiki I think. It allows us to split huge sources of information in one document into several documents that are easily linked to from other pages. There is a striking similarity here to the software design Single Responsibility Principle. A class as well as a document should only have one reason to change…

No special roles, instead accountability!

Usually, a wiki does not divide people into authorized and unauthorized groups of people. Naturally, only the group with interest in the wiki may gain access to it. But aside from this authority level, everyone in the group may write whatever on the wiki pages. Usually, this would go for the whole company as long as there are no specific security reasons to conform to.

However, although anyone can edit any page, a wiki should always provide an easy way to see what was edited and by whom. This means that accountability is there since it is always possible to see and compare the different versions of a wiki page. Also, wikis should provide an easy way to roll back to a previous version of a page. 

Having security restrictions often lead to more maintenance and trouble than what it is worth. If there is no top secrets on the page, let people view and edit the information as they want. If a change was bad, well contact the person for a verbal discussion and hopefully roll back the page afterwards after you have agreed upon what should be there.

As far as I know Microsoft Word does not provide any version tracking possibility on file level so this is often added manually in the file instead. However, the SharePoint platform does give you a versioning and roll back possibility for word files. However, I don’t actually know if it is possible to compare different versions of the word file with each other.

WYSIWYG vs. wiki syntax

Microsoft Word offers WYSIWYG editing. I.e. What You See Is What You Get. It means that MS Word hides the small symbols from us that make bold text go bold and underlined etc. I think MS Word does an excellent job at this (although there are still bugs) and the application has definitely reached a mature status.

I would say most wikis are not mature when it comes to WYSIWYG editing. They are far from as feature rich as MS Word WYSIWYG and often you find yourself cussing over a behavior or a bug that you are used to in MS Word. I believe WYSIWYG in wikis will probably mature during the next couple of years and that the difference will disappear.

However, the WYSIWYG editor, if even provided, is often not what the wiki user utilizes (at least not if he is a programmer searching for control of the tool…). Instead he goes directly for the wiki syntax which is simple to use. Unfortunately, there is no standard here and the syntax varies between different wikis. Bold letter in some wikis would for instance be rendered by adding a star between the word: eg. *This text would become bold when the page is saved and published.*

And a small summary

Well, I have lots more to write about wikis but this will have to wait for a future blog post. Probably, this is even now to long for a blog post. Hopefully someone is reading this eventually. And if you do: stay tuned for more…

 

Andrew Hunt and David Thomas have a written a great book called The Pragmatic Programmer. This book covers so much great stuff!  Most of the time, while was reading it, I found myself sitting with the jaw against my chest in astonishment of how clearly Andrew and David pinpoints problems and recommendations in software development. I think all seasoned developers would have the same feeling since the problems Andrew and David writes about are well-known, but not very easy ones to actually pinpoint and describe.

As a side note, at the Øredev conference recently, I saw Andy Hunt giving an excellent key note speech opening up the conference. There was quite a number of fascinating subjects he talked about and I hope to be blogging on some thoughts on these subjects in the near future.

Anyway, in the book, the writers bring up a term called software entropy as a force very difficult to avoid for developers. When I first heard of entropy it was actually in chemistry class many years ago. An explosion is an excellent example of a chemical reaction that renders a very high order of entropy. I.e. the amount of disorder of atoms in the explosion is very high in the beginning but rapidly goes back to a low level of entropy. Naturally, this is due to the high amount of energy that sets the atoms in motion.

There is a striking similarity with software entropy I think. When things are heating up in a development team and we are as busy little bees to meet a deadline, entropy is bound to be high. Or at least the risk is very high that the entropy gets high. As a cause of this, Murphy’s Law might appear out of nowhere which seems to be a result of just pure bad luck. But often it is the just the result of high entropy, i.e. the disorder tends to get high as we get stressed out and several accidents happens in a short amount of time.

The writers go on with an analogy to city buildings that are of very different quality in different neighborhoods; some buildings being very clean and neat while others in another area are in a very poor state. This is the effect of “a broken window”. If one window gets broken and it does not get fixed immediately, then soon another broken window will appear; and yet another and so on. Soon the neighborhood will look like skid row and criminality increases drastically.

That this is so, even Swedish governments have concluded. I recently saw a news program stating this very fact. And in the local news paper the same very fact got stated about a neighborhood not too far from where I lived. A whole city block is going to be torn down and rebuild and as a result, criminality is sure to drop it was stated. Well, good!

I think there is an absolute truth in this and that it can be explained with our pride. If you are not proud over the neighborhood you live in, you are not going to respect either the buildings or the people that live in them. But if you feel pride over a good, esthetic environment that surrounds you, you take more care of it.

As for software development, we have the same situation Andrew and Thomas states. If you don’t feel proud over the code that is produced in the project and honor its design, the software will begin to rot. If this happens, sooner or later you probably are going to have to throw it all away and redo the whole thing from scratch.

So, as the authors of The Pragmatic Programmer so wise fully states: don’t live with broken windows. Anticipating that the design of the software is a good one, follow it instead of doing small hacks in order to save time. That time you save may very well be 10 times the time lost further down the road when someone is trying to get the once upon a time nice design to work again as it should be.

I know: Software is never perfect and this is not what the authors, neither I, are saying. However there is a great difference between delivering good enough software and doing “hacks” to the system all the time.

Unfortunately there is a driving force that often makes these hacks necessary: the critical deadline of a promise made to somewhere by somebody by someone... But the underlying reason for this is often due to a crappy or not existing project methodology which is a subject that I won’t dig into in this blog post. However, this spring I probably will write a lot more about this.

 

The first time I heard the word ubiquitous, a sigh of utter and ignorant reluctance went through my mind. I figured that such a beautiful but complex word is absolutely bound to bear an over-complicated meaning to something that perhaps might be very easy. And unfortunately, that killed my interest at the time. Well, having understood the importance of ubiquitous language my interest is gained.

So what does it actually mean? Well, a quick search at my favorite place to look for strange words gives me a hint. When adding the word define: before a word, acronym, abbreviation whatever in google, a search will be done at a number of open dictionaries on the Internet. This is nice since the explanation of the word is given in a number of different contexts which gives me a broader meaning of the word. With this search, define: ubiquitous, 5 different explanations are rendered. The one I choose to show to you is this one:

omnipresent: being present everywhere at once
from wordnet.princeton.edu/perl/webwn

In Swedish I would translate this to “allomstädes närvarande” which is even more poetic I think. However, the English translation put us a bit closer on the map as to an understanding of the word, but we’re not there yet. What is omnipresent anyway? Is there really something that can be everywhere at once? Sounds like something I want to be…

Well, speaking about ubiquitous language, naturally we are talking about a metaphor. And after reading about ubiquitous languages in Eric Evans book Domain Driven Design and having combined this knowledge with my own experiences in software development, the pieces actually fall together.

Ubiquitous language is all about sharing a common terminology between people. This is an extremely important ingredient in how we communicate with each other. Without a common terminology there is no way that anyone can explain anything to anyone else. Or at least it will become a very, very difficult thing to do.

Let me take an example of this. Imagine that you are about to explain to you six year old son how he is to ride his new bicycle. Only that you are not allowed to use any words that actually describe such things as pedals, wheels, and stepping on the pedals. Of course you can always point at the things and call them “thingie” but try doing that as you let go of the bike and let him take off on his own.  Well, he is bound to crash the first couple of times anyway so I guess this doesn’t matter that much…

It is hard to find good illustrative examples, isn’t it? Well, I am working on my imagination in this area.

Anyway, in software development we have something that is called the domain knowledge. This is the core business knowledge that is associated with the application(s) to be built. Each company have their own business knowledge and thus also their own specific terminology for it.

However, unfortunately the same terminology is not always used across the company and towards customers. Marketing people will use some terminology when they speak to customers when they originally sell the terrific idea. Then developers probably name those very same things to something similar in the domain architectural design. Then suddenly, further down the road, marketing renames a domain term to something else much cooler and, u-hu, the developers are doomed… They feel that this name change is just not worth the pain of changing it in the software design also. Especially this is common when we are talking the database with live production data. Ouch, do not touch it, it may fall apart and it is deadly vulnerable, the heart and soul of it all etc… Once this name conflict has occurred, the terminology is not shared any longer. Instead all developers have to map their domain names to what marking people means with the provided functionality. This is an utter source of confusion.

Of course, a name change is not the only reason for a mixed terminology at a company and there are certainly most often more players involved than merely developers and marketing people. Lacking communication within a company or misunderstanding of the domain model is just as common source of a fractioned terminology.

So where does ubiquitous “thingie” come in? Well, the terminology that we use to communicate with each other should be as understandable and sharable as possible to everyone so that the same words for describing domain knowledge are used. Then we have a much better chance of actually understanding each other. Trying an illustrative metaphor again; it means that we could concentrate on fitting the puzzle together with the help of the puzzle images instead of trying to do the same thing merely using their geometrical size. At least this is the sensation I get when working in such a domain at a company.

If you know of and understand the domain model and you are about to explain it to new-comers in the project, then my advice is that you start with explaining the terminology being used in a document. This will make it easier for other to understand the domain since they can start by reading this before they get an explanation of what the applications actually does. Otherwise, you will most likely use specific domain language words in your verbal explanations that they have not have heard of before. This will probably make your audience miss the main points you are trying to get across.

Also, by extracting and writing the terminology you will get a better perspective of the domain that you consider as natural and simple but perhaps is not. Most likely, you will find names that are confusing and duplicate names meaning the same thing. If so, revise the terminology so that it is correct and up to date. Make sure that this is the terminology that is used throughout the company by discussing with people. Then you achieve a ubiquitous language which will let you stay focused on the real problems and how to solve these. 

 

I guess this is quite a dramatic blog title statement but unfortunately it is true. I am often cursing over regions I find in other peoples code. This blog post will tell you why generally I don't like them.

Both C# and VB.NET allows for a feature called regions. Regions at class level may look something like this:

Now, the benefit of using regions is that you may collapse them easily when you are not currently working with them. Many regions could then look like something like this

 Of course, in a real scenario, you would have a more real case choice of selecting regions as to group class members. I’ve seen that it is common to group methods and properties etc. according to member accessibility level, i.e. private, protected, internal etc. Also, it is quite common to group regions of common member functionality;  kind of like having inner classes but categorized as regions instead.

To make things worse, C# allows regions to be defined within members too:

So, how come I don’t like this? Well I have a couple of reasons for this:

1.       Regions at class level make the code harder to work with. I think most advanced (lazy ) .NET developers know that the Visual Studio short cut keys Ctrl + M + O collapses all methods and regions in a class. This action gives a quick and good overview of either the members or regions in the class. Even though you may expand/collapse a specific region with Ctrl M + M, it is quite a hassle to have to expand both regions and methods to get an overview of the actual code within the method. I think that an overview of the functionality of a class is best given by the natural language constructs themselves without using regions. Once you start adding regions to you code, you add an additional expand/collapse step in order to be able to start working with the actual code within you methods. This makes the code harder to work with.

2.       Often, when regions are used at class level, it is done because there are too many members in the class to keep track of. This means that the cohesion of this class is low which is bad. Another, very similar principle, founded by Robert C. Martin, is the Single Responsibility Principle. Regions tend to make you violate this principle since classes become too large and contain too much mixed functionality. More on this in a future blog post…

3.       Regions within methods share a common symptom. When regions are used within a method, it is likely done so because the method is very long. Too long if you ask me. Methods should be short and be easy to read and understand. Otherwise they will break what I usually call the Divide and Conquer principle.  In short Divide and Conquer in software design, as I choose to define it, is a major problem split into many smaller problems by decomposing a method into many smaller methods. This is how you understand and solve a major problem a lot easier since you don’t have to be keeping too much detailed information in your mind at the same time.

4.       When you use regions within a method, it is much more difficult to track the actual data flow between different regions. If local variables are used, and not state fields, you can easy see the API for each method. I.e. you see what input data each method needs and what output data it delivers. Regions within methods do not give you this and the code becomes much more difficult to understand.  

5.       Regions within large methods have another problem: if you receive an exception in operation and if you are logging the stack trace of the exception, you have a much more difficult time to track where the actual error occurred. With smaller methods instead, you will at least receive information in which method the error occurred. (…and of course you should not compile your code with the debug flag to true in operation environment…)

Well, these are the negative consequences of regions that I have come up with so far. Of all these negative aspects of regions, I think the potential violation of Single Responsibility and Divide and Conquer Principles are the worst ones. From what I’ve seen, regions tend to make programmers forget that they are developing in an Object Oriented language and instead program as if using a functional programming language. Sure, functional programming languages have their strengths, but improved readability and therefore better maintainability is not one of them.

So. Is there a place when regions actually are ok to use? Well, if someone has placed a region to group some less significant members of a class, I might accept it although I probably would not define the region myself. However, I will never ever accept regions within methods since I think this violates the principle of Divide and Conquer.

Though, I have found one case when I actually use regions myself. I find them excellent to use when I am constructing demos for course material. Regions let me hide code and comments that I don’t want my students to see yet. Alas, I use regions strictly for educational  purpose. Wouldn’t the world be a better if everything just was a big nice demo…. However, it is not. So lay off those regions in your code. Please.

I started out the chronicle  that I recently wrote giving an angle at the information society we live in today. This is also what I will cover as a starter in this first web 2.0 blog post.

For developers, the information society is very real indeed since the knowledge base required for programming is huge these days. I have only been in the industry for about 10 years, but even in this time I can surely notice the change from when I began. In the .NET field alone, which is my field of specialty, there are thousands of classes that are good to know of. It is not always that documentation provided from Microsoft covers the need that exists.  Also, the number of frameworks, libraries, components, third party open source products, tools etc seem to have exploded the last couple of years. It is not easy these days to call yourself an expert developer of .NET; Nor in any other programming domain for that matter. Most, if not all, people don’t call like to be called experts in such a broad field because of the expectations it may raise. My experience is that an overall humble attitude resides when it comes to programming knowledge nowadays. Something that is quite alright I think. We should be humble for the unknown I think.

Anyway, for developers, the provided information on the Internet has become a reliable source of information. This includes blogs, communities, articles, wikis etc. There is less of a need for developers today to keep track of all intricate details of language and frameworks since there are so many resources available out there. So many people share their experience in blogs and communities which many times makes is quite easy to find a solution to a specific problem.

However, we do have to distinguish between semantics and syntax. Syntax being the language we program in and I dare to say knowledge of the Frameworks provided to us; Semantics being how we program in the language and Frameworks. Both types of knowledge are to be found on the Internet. Semantics, however, is so much harder to learn than syntax knowledge. Semantics deal with the architecture and the design of software and this takes knowledge (lots of reading) and experienced practice (lots of programming).  We are talking years of studying and programming in a professional domain specific environment. The funny thing is that even though I think I’ve reached perhaps the middle of the tunnel, occasionally it seems like I am thrown back to the start of it due to some new experience or gained knowledge. What other profession allows you from time to time to have the sensation of being a rookie again?  To me, this is fun. And frustrating.

Well, this blog post kind of made the introduction of what I am hoping to become a series of blog post in the web 2.0 field. I have many thoughts to share, especially when it comes to wikis as software development tool in software projects. So stay tuned for upcoming post if you’re interested of my thoughts.

For about a year now, I have on a monthly basis been writing a chronicle for the Computer Sweden magazine. I receive a software developer related question in various software areas each month. Most of these chronicles can be found here, but you will need to be able to speak Swedish in order to understand them… J

However, each month I do end up with the same kind of struggle: to shorten the chronicle to the text length I am allowed to have. There is absolutely nothing wrong with this. On the contrary I think a chronicle should be enjoyable and somewhat light weight to read, not covering too much details and especially not be too lengthy. In short: enjoyable to read. Don’t know if I accomplish this really but I do my best.

However, it is really difficult and a very special art of writing to be able to be precise and tell something meaningful on a limited length of text. I believe it was August Strindberg, a quite famous Swedish author who once said: “I do not have time to write short”. Now, I am definitely not comparing myself with Strindberg but I do understand what he means. All too often I have been writing emails to my colleagues at Dotway that perhaps have been a few pages to long (pages being a metaphor obviously... J ). Some colleagues have even coined such long mails as “Tobias mail”… all to my utter frustration of course. I dare to say that I really do try to shorten long mails down, but sometimes this just takes too much time to go all the way. I always do spend long times reviewing such long mails so that the structure is ok and understandable and that spelling and grammatical is ok. Anything else I think would be disrespectful to whomever I am writing to since I am opting for precious time on my account.

As a side note: The last couples of month I have a couple of times successfully changed tactics going from quantity to multiplicity … J Maybe this is the road to take.

When it comes to the Computer Sweden chronicles, the editors leave me no choice and I really have to spend time to be brief and consistent. Even though I occasionally has slipped the quota and received a gentle and friendly mail distributed slam on my fingers from the editors, most often I have been able to keep myself at a maximum of 120% of allowed text length... Anyway, I am thankful to the Computer Sweden for giving me this opportunity to practice being brief and nail those specific points.

So why am I writing all of this? Well first of all because it is my blog. I can write whatever I want in it without bothering if people will read it or not. Second of all, in the last chronicle I wrote, which is supposed to be published soon, I did add a reference in the end of it to my own blog. Why? Because the topic, web 2.0, is huge! I actually have a lot of more thoughts on the subject than what I could fit into the chronicle. And the chronicle being a web 2.0 chronicle, it seems like the perfect ending for it too. J So after this --- ehem --- rather lengthy blog post, I intend to get right at writing a blog entry about web 2.0.  

This week I finally did something about my blog engine. I have gotten tired of the DasBlog skin I was using so I found another one that I liked. So finally, I downloaded the last version of DasBlog v2.0. It was over 2 and a half years since I looked at the source code the last time (open source) and it seems like people have been doing a great job since then bringing new functionality to it. I am not sure if I like/understand everything that I see in the code yet, but it is definitely an amazingly good open source project. Many thanks to those of you who have contributed with your time to make this possible!

Btw, there might be some errors still on this new site of mine due to missing configuration, so please let me know if you find one. Promise I’ll buy you a beer next time you’re in Gothenburg if you do

The 8^th of November Dotway will give our first breakfast seminar in Gothenborg. It is free of charge and everyone interested in the subject are welcome. I know that my two collegues Björn and Truls have moslty looked into the 1.1 version and it is going to be a thrill to see it for me also. This is actually Dotways first "seminar tour" in Sweden and the seminar will be given in Linköping later on during the afternoon and in Stockholm on the 9^th of November in the morning. You can read more about it here: www.dotway.se/silverlight. 

So far I've only got 6 people signed up and I know they have had a full house twice in Malmö. ;( Well, well, hopefully more people will hear about this. The more, the merrier I think.

Wow! Emabarrasing. I didn't realize it was almost a year since I made a promise to keep writing in my blog... Ok. Now I make a new promise, here and now: to never make any promises about writing in my blog. That's definitely a more easy one to keep. Allthough I do actually have a lot of subjects piled up that I want to write about and I hope that I can get started at it in november. But that's not a promise..

I have just spoken about Model View Controller at Pimp My Code that Cornerstone arranged. Yesterday in Stockholm and today in Gothenburg, Sweden. It was a great event and my brain is boiling down all the impressions I got during these two days, Both from hearing the other, in my opinion, excellent speakers but also just from the atmosphere during those two days. Hopefully I will get to do this again.

Anyway, I did promise to hand out my code demos in my blog and here they are: MVC demos.7z (167,42 KB).
(Download 7-zip here). I was worried for a while since out of convenience I placed the SQL Express server database (files) in all projects that needed it. Well, the database had a size of about 2 MB (although very little content) which rendered a total size of about 23 MB.. But 7zip did an amazing compressing job so I think I am home free.

Now, some words about the demos. I did write them all this weekend and rather hastily. I did do some refactoring as I created the next demo and so on, but I did not bother to clean up the old ones. But the total code mass is so small as it is so that should be no problem to you. Also, I wanted the demos as clean and simple as possible in order to demonstrate different aspects and flavours of Model View Controller. Hopefully I did manage this. Although I do admit I would have liked to tidy the code a bit. But what the heck. Enjoy or destroy.

Nevertheless, feel free to contact me if you have any question about something. My name is tobias.fjalling and I work at dotway.se. I think you can figure out the rest.

Here my powerpoint slides too: MVC.pdf (0,4 MB)

PS. I just gotta do something abour this crappy blog GUI of mine. This is embarrasing too...

Last week, the Öredev 2006 conference took place. I though it was a great event and I listen too many interesting speakers. I'll probably get back to write some reflections on some of the sessions in later blog posts.  My own workshop session took place last Tuesday and I was assitested with Göran Halvarsson at Dotway for this session. I thought the workshop went fine although I have'nt taken part of the workshop evaluations just yet..  As I been writing previously, the workshop was based on the ASP.NET AJAX July CTP rather than the newly released beta 2 version.  Not that it mattered that much I though since the concepts are the same.

I just sent the workshop labs and the instructions for the walkthroughs to Michael Tiberg, the project leader of Öredev, so they should be dowloadable from the Öredev website soon.  However, I've put in a lot of effort to convert the labs into the beta 2 syntax. This is quite cumbersome since much of the client control documentation still is missing at the ajax.asp.net web site. I'm almost done however, and I promise I will write about my endevaours with this matter in a future blog post.