Monday, 23 December 2013

The Devils in the Documentation....not quite but its a start!

So being a software engineer I find myself getting frustrated with the lack of emphasis put on maintaining light weight documentation. Now don’t get me wrong heavy weight documents outlining every single intricate detail of a piece of software is not only a waste of time to the person writing it but also a waste of time for the person reading it. When you start working on a piece of software, particularly something new to you, you need a few things to get you going and point you in the right direction. 

One is the existing code base, ideally nicely written and self documenting with meaningful class names, method names etc and a little magic which isn't avoidable. Another must if you are going to be working on a meaningful/sizeable feature is a basic overview of the system, its interactions basic concepts. Not only do you get a feel for how things currently work, you get a feel for how they fit together, how you can add value, how they may interact with other systems. You get a snapshot of naming conventions and vocabulary which hopefully should be mimicked in the code base. There is a useful tool call code-words for extracting out word clouds used within a code base, run it against a code base you are working on and see what you find, it may be interesting. Combine these things together and getting up and running on a new project or new feature is much easier in my opinion. I don’t even have a preferred type of document of diagram, sequence diagrams, UML heavy weights, simple process flow diagrams, these all can bring value and are better than nothing. Obviously the caveat is that you need to ensure you include the time needed to update these bits of documents and diagrams as you add value and change systems over time otherwise they get out of date and tell a different story than what is really happening. Diagrams in my opinion are much easier to update, easier to maintain and much more fun and enjoyable to work with. They don't always show you the fine grain details which you need, in my opinion these are found in the code base and possibly in more focused diagrams looking at particular interactions or solutions.

I think the real point here is that the documentation of a system needs to be treated with respect just as the code, the tests, the infrastructure and the business itself should be. The devil is always in the detail and the details are going to be in the code base or peoples head, the documentation will give you means to pin point where to find the details and hopefully not make assumptions which turn out to be unfounded. 

I feel that this relates to all software engineering I have done, open source, personal and at an enterprise level. This post is purely a complete rant after hitting several issues to do with the lack of knowledge or information when working on projects professional and in my spare time....rant over! Basically stop being lazy and give me a simple digram!!

James Morgan

Sunday, 13 October 2013

Cinnamon Applet Development

Having been back from travelling and before strting my new job I've had some from time. Over the last week I have been playing around and looking into improving an old project which is an Cinnamon Applet which interacts with GitHub's API and displays details on a persons public repositories. Written in JavaScript and utilizing any underlining Cinnamon code via GObjectIntrospection its reasonably pleasant to work with, given a nice editor such as gedit with a few plug-ins. I do have a few gripes with Cinnamon Applet development but I will get to this later in the post.

The applet is can be installed via the new applet management console in Cinnamon 1.8 which now displays published applets from the Cinnamon website as well as installation and configuration. Along with other improvements Cinnamon 1.8 now has a fully baked in Settings API which means that developers like me don't have to have a home brew solution to this issues, previously I was using GTK Glade and some custom JavaScript code to control this, the addition of the Settings API makes it a much easier and hassle free even if its not got all the features I wanted.

The Applet has improved after a few rounds of re-factoring plus the additions of a few features such as correctly using the HTTP headers and hopefully not exceeding your free public API limit which did happen occasionally. I have also added change notifications which means that if the number of issues, forks and watchers changes for each repository then I pop a notification to the user about the change with a link to the repository, its basic but can be useful, I plan to improve/expand on this in a future release.

Next on my list of things to do is to give the option for users to use GitHub 0Auth Token authentication and to increase the complexity of the plug-in. I would like to give users more options for what they see and use in the applet, expanding the controls. Its nice to learn new things especially something community driven like Linux Mint development. Having used Linux Mint for 18 months solid as my main desktop and development environment I feel it was a wise move and one I don't regret. I use Windows 7 and Ubuntu in my day to day job as a Software Engineer and they don’t feel as nice to work with and don’t give me what I want from a desktop experience. I believe Cinnamon and Linux Mint have a good future and look forward to seeing whats new. N.B. Cinnamon 2.0 has just been released.

The application can be seen in more detail on the Cinnamon website and all code and further information can be found in the GitHub repository. Let me know what you think.

Gripes and Grimes

Settings API

The Settings API is nice to work with and even has some good documentation and a few example can be found online which is good. I would how ever like more controls available for what options would be displayed. For example in a normal configuration option I would tend to put links to various websites, display version numbers and also have small blocks of text highlight things and or simple displaying help etc. 


This is just a general wine about the state of documentation for Seed and GJS, I know there are sites available such as this but when you have never done things before it would be nice to have an example of how to interact with the API's and how to overcome some basic coding problems. On a good note the Linux Mint development time are always on IRC and always try to help if they can.

Unit Testing
Coming from a Java background and writing unit tests and aiming to be test driven at work everyday I find it hard writing code without tests. In essence what happens when combined with the lack of documentation is, I write some code which I don’t know even compiles, install it, restart Cinnamon and see what happens. On several occasions I have got myself into issues and even and to restart my machine. Maybe there is a better way to develop these applets and extensions but I'm not sure what that is, there certainly isn’t first class support for it yet.

I know that in reality since its all Open Source I should really try fixing the grips I have raised., maybe this will be next on my list of projects.

Sunday, 22 September 2013

Back to the Land of Nod...

Having landed from our 6 month travelling trip around SE Asia and a bum numbing 36 hour journey including a truck, boat, bus, three flights and a car journey I have arrived back in the U.K. Amongst other things I have a long and extensive list of jobs, projects and tasks needing to be done to get back into the world of Software Engineering and computing.

I have a few ideas of various applications both web and mobile based which are related to travelling and which I will investigate the feasibility of, technology and any possible existing apps, maybe only writing them down in some detail whilst they are fresh so when time permits I can attempt to make them. I have a Linux Cinnamon plug-in which hasn’t been working for nearly 3 months since GitHub changed their restful based API and I have been unable to change code and commit any fixes whilst being away, some users reporting issues and it looks like popularity had dropped because of it. I plan on refreshing my Linux Mint install with the latest version and generally cleaning up my PC which before I went again always seemed to be last on the list of things to do on a weekend for obvious reasons. I have literally thousands of emails from various mailing lists I am members of which to be honest I will most likely just clear out and start again, picking up with the latest chatter and developments from now. Of the probably 5000+ emails I reckon only about 100 are relevant which relate to things I need to follow up on check and take some action, many off which are job related which before I went away I paid little attention to, oh how this has changed! Obviously I need to start thinking about jobs and where to work, what to do and where to live, updating my CV (Resume Link) and LinkedIn profile.

I have travelling related jobs as well as well including sorting out the thousands of photos I have form the trip, selecting some to show friends and family since I don’t think they can endure spending an entire day looking though so many. I have washing and other clean up jobs to do from the trip. I have a few blogs to post from the travelling along with getting used to British weather and generally just getting used to be in the U.K.

Not only has travelling been eye opening and truly the most enjoyable thing I have ever done it also allows you to completely disconnect yourself and clear your mind, not being connectable by phone, text or Skype (unless you want to), not having a PC or laptop and just having a small phone to check your emails and write the blog (occasionally), not having to perform your daily routines and chores has be highly enjoyable and free. I hope to take from it so much but also just a fresh and clean start not only in body but in mind and perspective on things from work, life, family, friends and everything else that they entail and mean to me. Technology and engineering was a passion of mine before I left and I don’t plan to change this, maybe the way I code will change, maybe not, hopefully the way I interact with people will change, maybe challenges will seem smaller?

I have work to do...


Wednesday, 22 May 2013

Hacking from a phone, not the easiest

Recently I've had two people fork and contribute to an open source project I created to add GitHub integration to Linux Mint, inparticularly cinnamon the replacement window manger. Not only was it great to find some people actually using my app but I also really appreciated GitHub for its social and open nature. Using it in a closed cooperate environment does work but when you sit next to the people who are working on the same code its always best to speak to someone in person as opposed to simply commenting. However this isn't always possible and GitHub provides a good medium for this. Both contributions came from forks woth pull requests which allowed for good two way communication and code reviews etc. The problem I did have is that as I'm travelling I have no access to my linux mint install, my GitHub, development and testing tools so it had to be checked, merged and released from my phone, it took a very long time! Hacking from my phone was hardly hacking as the toolset available to me a text editor, zip/unzip application, browser and GitHub app (which has limited functionality). I managed to check the code on the pull request, do some reading, merge it in to master and when it came to a release I downloaded and extracted the zip of the main repo, copied some files to a new folder, tweaked some text and zipped it back up. I also sent it to one of the contributors for a quick test. I can upload the zip with the browser and hopefully a new version will be out and have some new features and bug fixes. Not bad from a phone I reckon!


Thursday, 21 March 2013

Embarking on a big one!

Approximately 4 weeks before we embark on one hell of a big adventure with +Isobel Perrin my mind is starting to wonder, what the hell am I going to do if I cant write any code for 6 months! I code, no IDE, no Java, no JavaScript, no AngularJS, no morning standup, no banter with the team, no late night hacking, no diagrams, no mailing lists....the list goes's going to be a challenge!

Hopefully this will soon subside and with my newly created account on Cloud9 hopefully this will hit the spot with any crazy urges to hack away, not entirely sure how well it will work on a nexus 7 though?

The intended itinerary is as follows:
  1. China
  2. Vietnam
  3. Cambodia
  4. Laos
  5. Thailand
  6. Indonesia
  7. Malaysia
  8. May be somewhere in Europe before we had back to reality
Being nearly a year from birth to actual reality and having privately spoke about it for years I have mixed feelings about leaving work, dropping my routine, not having regular contact with some great friends and colleagues but in reality these opportunities aren't easily come by so why worry, things wont change that much in 6th months. Yes I will be Jobless, homeless and probably a little work shy but helpfully I will return a decent and hopefully more enlightened and worldly person.

Please follow my new blog space to keep track of our adventures, I will update when can!

Saturday, 13 October 2012

MAven Enforcer Plugin Example

A little snippet which I have found useful when enforcing maven dependencies in a project, below is a Gist which demonstrates how to fail a maven build via the maven enforcer plugin for Log4j and commons-logging

Wednesday, 8 August 2012

Reloadable Application Properties with Spring 3.1, Java 7 and Google Guava

The Problem

 One common problem I have experienced when developing applications especially web applications is having the ability to specify application configuration properties at start-up or runtime. This problem isn't an old problem and has defiantly be solved over and over again by many frameworks and libraries out there. Spring provides the ability to specify properties files for use inside your spring application and nicely provides spring expression for looking up properties values and setting them on class files etc.

One thing I have always wanted to achieve is the ability to have a property re-load itself if the properties file ever is changed, although this may seem dangerous it does mean that an application wont need to be bounced in order for a new property to take effect (in theory).

One of the great new API's in Java 7 is the WatchService API, this is handy set of tools which allow you to watch and react to file changes. Other libraries are available and have been doing this for some time but this is a good opportunity to get stuck into some of Java's new features and evaluate its usage. 

From the Java Doc:
A watch service that watches registered objects for changes and events. For example a file manager may use a watch service to monitor a directory for changes so that it can update its display of the list of files when files are created or deleted.

Spring provides functionality to load application properties via a PropertyPlaceholderConfigurer class, this is used to configure the application container giving exposure to each properties file and its properties specified allowing them to be referenced to configure the application.

What I have created is a proof of concept library which allows class fields to be set from properties files via a @ReloadableProperty annotation. These properties are also auto reload if the given properties file changes during runtime.

How it Works

When Spring starts an Application Context an implementation of Springs PropertySourcesPlaceholderConfigurer is instantiated to perform additional logic when loading and setting values from a given set of properties files. (see: ReadablePropertySourcesPlaceholderConfigurer)

During the instantiation phasae of an Application Context a new instance of InstantiationAwareBeanPostProcessorAdapter is also created which allows post bean processing to occur.

Google Guava is used to implement a simple Publish & Subscribe (Pub-Sub) Pattern so that beans can be updated once created, i.e. a bean can subscribe to property change events. (see: EventBus) EventBus was chosen as it is a very easy and simplistic way to implement loosely couple object structure. (see: blog)

When each properties file resource is loaded a PropertiesWatcher is started and attached to the given resource set, reporting on any java.nio.file.StandardWatchEventKinds.ENTRY_MODIFY events from the host operating system. When an ENTRY_MODIFY event is fired firstly the resource changed is checked for property value changes then any bean subscribing to changes to the modified property has the specified field value updated with the new property. Once the field value is updated no other operations are performed on the object.

Each resource specified starts a new thread per parent directory i.e. two properties files in the same directory requires only one ResourceWatcher thread, three properties files in three different directories will start three threads.

Example Usage

Sample Bean Usage

Sample XML Configuration

Sample Properties files

Future Changes

  • Ability to use Spring Expression language to map properties files
  • Support for Java 7 Data and Time classes
  • Include the ability to define a database driven properties source not just properties files
  • Implement error recovery inside PropertiesWatcher.class, including better thread recovery
  • Ability to perform additional re-bind logic when a property is changed, i.e. if a class has an open DB connection which needs to be re-established using newly set properties.
  • Replace callback Properties EventHandler with Guava EventBus
  • Ability to configure usage via Spring's @Configuration


As on reload I simply reset the field value for future use, if the property was ever used to create another long lived object there is no way of re-binding or performing additional post reload logic on a class, this could be done but would need a marker to identify what to invoke post reload i.e. annotation of a void empty args method or implementation an interface which then can be triggered ever time a classes properties change and perform additional re-binding logic.

Feedback always welcome and it would be nice for someone else to check this project out and review it/use it. A complete project with sample tests can be found @