Archive for November, 2008

Writing clear code: One class must have one responsibility only…

Tuesday, November 18th, 2008

A site that I regurlarly visit the last few weeks is stackoverflow

It's a site where different software engineers write about all kinds of aspects of software engineering and writing code.

The most interesting threads to read are the threads that affect HOW a software engineer actually WORKS the entire day. how to persuade programmers for different ways of working is an interesting example of such a thread.

Lets make that more concrete. The best code you will ever write is code that can easily be READ.

Therefore: A good code writer is a good writer.

One of the most difficult things is to keep your code clean of multiple meanings. With that I mean that classes (or even methods) can so easily be re-used for slightly different reasons which risks the code to not be readable anymore. Classes and methods should only be used for a single purpose. That does not mean that methods cannot be called multiple times, from different parts of the code, sure they should, but methods should always have a (ONE) clear meaning and not be misused for multiple ends. Just as classes must only have a single responsibility to exist…

For example in the following scenario…

Frontend->PresentationLayer: GetHotels
PresentationLayer->ServiceLayer: GetHotels
ServiceLayer-->HotelProvider: SearchAvailability
HotelProvider-->ServiceLayer: Hotels
ServiceLayer-->DB: GetHotelDetails
DB-->ServiceLayer: HotelDetails
ServiceLayer->ServiceLayer: CombineResults
note right of ServiceLayer
    Combining HotelAvailabilityResults and
    HotelDetails into 
    set of HotelResults that can be
    displayed.
end note

ServiceLayer-->PresentationLayer: HotelResults
PresentationLayer-->Frontend: HotelResults

(btw: image sketch easily made through http://websequencediagrams.com/
…we have two calls that generate a list of hotels. One of the calls gets a list of hotels that are available (this information is retrieved from a hotelProvider), and the other list of hotels retrieves all of the nitty critty details of all the hotels. Think about the urls for every image for hotels, all descriptions about the hotel (how close to the airport or closest trainstation) and of course all the detaildescriptons about the rooms in those hotels.

The thing is: it is easier to create both of the lists with just one "Hotel Class". But as the sources of information are completely different, so will the contents of both of these lists.

Therefore we should have a class for hotels that immediately provide the information that the hotel in that list is an available one (HotelAvailable class), and another class that says that the class holds all the stale detailed information (HotelCachedInfo class). Both of these class will be combined in the Hotels that we want to present to the user. (note: that is a third! responsibility), so that will be a third hotel class.

It looks cumbersome to create different classes that might look alike, but when you later on change your code to add feautures it will save time…