Documenting your code with comments in Xcode 5

One of the nice new features introduced in Xcode 5 is the ability for source code comments to be used as documentation displayed in the Quick Help Inspector, in a Help Popup, and for Code Completion. I believe that this is made possible because Xcode now uses exclusively Apple’s own LLVM 5 compiler (GCC support has been removed), so it can build this functionality right in, since the compiler processes the comments along with user code. This kind of feature has long been available for users of other IDEs, such as Eclipse, and so this is a very welcome addition to Xcode, particularly as it might encourage developers to better document their code.

You can use either Doxygen or HeaderDoc format for the comments. As I come from a Java background I like to make the comments as close to JavaDoc as possible.

Here’s a simple example. This is a declaration for a utility method to check whether a file at a given URL has a newer time-stamp than another file at a given URL:

In my configuration of Xcode it looks like this:

Xcode method

Xcode method with comments

The comments sit right on top of the method declaration in the header file. There’s no point in putting them in the matching implementation file as we need these comments to be part of the public API.

The comment opens with a /** block start and ends with a final */ block end. After the block start I’ve added a general description about what the method does. Then I’ve opened a @code tag and provided some code for example usage (this is a bit like the <pre> HTML tag). The @endcode tag closes it. Then I’ve added a @see tag which will appear as “See Also”. After this are the important tags used to document the two parameters and the return value. These are @param and @return. Note the @c tags in the “Returns” description which serve to display the following word using a monospaced font.

Note that it’s important to save your source file in order for Xcode to detect a change to the file and regenerate the documentation from the comments.

Now that this is done, if we select the method in the editor either here in the declaration, or as implemented, and then Option-Click on it we get the Help popup:

Xcode Help Popup

Xcode Help Popup

And it will also display in the Help Inspector:

Xcode Help Inspector

Xcode Help Inspector

And also will appear for Code Completion:

Code Completion

Code Completion

As a bonus, if we want to ensure that we get the spelling of the names of the parameters right, there’s even a project setting built into Xcode that will check and warn us:

Xcode Settings

Xcode Documentation Comments Settings

Now, if I create a typo in the documentation I see this:

Xcode Warning

Xcode typo warning

Clicking on the yellow triangle leads to a very helpful suggestion:

Xcode Assist

Xcode Assist

And that’s about it. A very nice and welcome addition to Xcode. Now that Apple is focussed on only supporting its own LLVM compiler in Xcode, I hope we’ll see more of these types of features in future versions.

Archi – an Open Source ArchiMate tool (part 4)

(Continued from Part 3)

Impact and Popularity

In this final blog post in the series, I want to examine the impact and popularity of the Archi tool.

Archi 2.4 was released in December 2012. In the previous two years of development I had implemented a fairly respectable feature set, and devised some unique features, thanks to a source of funding that paid my wages, and the feedback and enthusiasm of Archi’s users.

archi_viewpoint_total

Archi 2.4

Just how popular has Archi been? And how popular is Archi right now? I suspect that it has been, and still is, very popular.

In 2011, Christina Smart, from a Jisc-funded organisation, interviewed me for a blog post, Business Adopts Archi Modelling Tool, and I spoke of the possible reasons for the extensive adoption of Archi, especially in the business sector:

CS: Archi has a growing number of users outside education, who are they and how did they discover Archi?
PB:
…I am also aware of other commercial companies using [Archi], but how did they discover it? Well I think it’s been viral. A lot of businesses spend a lot of money advertising and pushing products, but the alternate strategy is “pull”, when customers come to you. Archi is of the pull variety, because there is a need out there, we haven’t had to do very much marketing, people seem to have found Archi on their own. Also the TOGAF (The Open Group Architecture Framework) developed by the Open Group is becoming very popular and I guess Archi is useful for people adopting TOGAF.

CS: Why do you think it is so popular with business users?
PB: I’m end-user driven, for me Archi is about the experience of the end users, ensuring that the experience is first class and that it “just works”. It’s popular with business users firstly because it’s free, secondly because it works on all platforms, thirdly because it’s aimed at those making their first steps with ArchiMate.

When I spoke about the concept of “pull”, I was referring to the book, The Power of Pull, by John Hagel. Tom Graves, the author, Enterprise Architect, “business anarchist”, and self-proclaimed “confusionist”, once said to me, in a telephone conversation, that he thought that Archi’s popularity was due, partly, to this “power of pull”. Archi had no advertising budget, it had no pushy salesmen, nor was it ever promoted in any significant way. Instead, users discovered it by word-of-mouth, by a friendly recommendation, or via a simple Google search. Together with an agile feedback loop between developer and users, popularity increased. Users clearly liked the whole package – both the developer and the product.

This is not rocket science. For me, this approach comes easily and naturally. I only have to think of the products and websites that I like, and think about why I like them, and just do the same. The key is to be open, clear and honest. People will come to you. I’m not a big fan of websites that claim to be selling a software product but where you have no idea what the software does, how to download it, how much it costs, or what it looks like. Instead you get a series of stuffy “white papers” explaining the benefits of nebulous “solutions” written in MBA sound-bites. Nor did I employ the “push and grab” approach – flooding the twitter-verse with tweets telling us of the “Top reasons to get a grip on the latest #archimate and #togaf trends!!!! Read our new white paper!” I know where “white paper” belongs in my household...

If you look at the front page of the Archi website it’s immediately clear what Archi is, does, how much it costs (nothing), what it looks like (screenshots), and where to download it:

Archi is a free, open source, cross-platform tool and editor to create ArchiMate models.

And I strongly believe that even the largest of organisations can relate to this honest, no-nonsense approach. That’s why I call myself a “code punk”. The software may only play three chords, but they’re honest and powerful ones.

Statistics and Google Analytics

I think we can get a sense of this popularity by looking at some statistics for that period. The old Archi website (no longer maintained), was tracked by Google Analytics. First off, let’s take a look at the figures for the year previous to when this blog post was written (September 21 2012 to September 21, 2013):

Site Visits

Archi Website Visits

Here we can see that in this yearly period, there were 71,752 visits to the website, of which 44,444 were unique visitors. Taking the unique visits alone, that’s about 3700 a month, or about 850 a week. Not bad. We can also see that a large proportion of visits (10,558) came from the Netherlands. This is not surprising given that ArchiMate is, as well as cheese and tulips, a Dutch product. The UK and the US follow closely behind. Here’s another view of the demographic location data:

Analytics Archi Location 20120921-20130921

Archi Website Locations

It’s interesting that India and Russia are in the top 10. Russia has a thriving community of Archi users, perhaps due to the fact that it was translated into Russian by Anatoly Levenchuk from Moscow. Again, this is an example of how the Archi community has contributed significantly toward its success.

Software Downloads

But what about the download numbers of the actual software?

Archi Downloads

Archi Downloads

Let’s take the figures for Archi version 2.4.0. Here we need to make some adjustments because Archi 2.4.0 was released in December 2012, and this reporting period starts from September 2012 (hence the figures for Archi 2.3.1). Therefore, this represents about 9 months for Archi 2.4.0. Adding up the numbers for the Windows executable (8,374), the Windows zip install (2,671), the Linux version (487), the Mac 64-bit version (360) and the Mac 32-bit version (67) we get a grand total of 11,959 downloads of Archi over a 9-month period. That’s about 1300 downloads a month.

It seems a lot. We could knock off a percentage for duplicate and failed downloads. But then again, these figures only show who actually clicked on a download link on the downloads page. There are probably direct downloads linked from other pages and referrals. Also, some organisations that I know of roll out only one centralised copy of the software throughout the company, so this might only show as one download, or not show at all if they have a direct link.

However you interpret these figures, I feel confident in thinking that Archi is probably the most popular ArchiMate modelling tool. Of course, this assumption is based on these download figures and the many emails I’ve received over the last three years. Put it this way, there are a couple of Fortune 500 companies that I know of, and some very large organisations that use Archi as their only ArchiMate modelling tool. I believe also that a couple of large training organisations use it as their training tool. Given that it was only meant to be a “starter” application, I find that interesting.

Archi has come a long way since its initial incarnation as a “proof of concept” tool.

Futures

Where now for Archi? I no longer work for the organisation that hosted the original development work on Archi and it’s time to move on! Also, Eclipse, the software framework on which Archi is built, has changed radically with the latest version 4, and this introduces some new challenges which need to be solved. The answer lies in the fact that the software is open source. All of the code can be found at GitHub, and is released with a MIT-type licence. If Archi is to be sustained, it will need to be migrated to Eclipse 4, and it needs to implement some of the most requested features from its hundreds of users. This will require the input of other developers, and so the next step is to get more developers on board.

I’d like to say thanks to all Archi’s users and supporters, for playing their part and allowing it to happen. It was, and is, I think, a success. With around 1000 2000 3000 downloads each month I’d say that Archi is quite popular.

Update 4 October 2013 – I’ve created a new and supported Archi website at http://www.archimatetool.com

Update 11 March 2014 -We are now seeing around 3000 downloads a month of the latest version of Archi at http://www.archimatetool.com. Since I set up this new website, Archi’s popularity and reputation has doubled and we’ve also attracted some additional developer interest.

Archi – an Open Source ArchiMate tool (part 3)

(Continued from Part 2)

Release early, release often

A very early version of Archi was ready by mid-March 2010. I demoed this to a roomful of enthusiastic delegates at an Enterprise Architecture Practitioner Group (EAPG) meeting in Birmingham, UK. It was warmly received. The features were very basic, but there was enough there to whet the appetite.

An alpha version of Archi, version 0.7.0, was released on April 8th 2010. Even though an alpha release, this version actually implemented most of the core functionality. All three ArchiMate layers were implemented, as was support for multiple Views and you could save the diagrams as image files. Further alpha and beta releases were made in April and May 2010. These versions focussed on fleshing out the feature set, bug fixing and getting early user feedback.

The official public version 1.0, was released on June 18th 2010 in time for the summer EAPG meeting. This version implemented the main feature set together with all the “hints” available in the Hints window, and Help documentation. Again, it was received well. We also had a website, a Google forum, and a small, but growing, Archi user group. The 6 months were up. (I should add, not to promote my ego, that this was all done by myself – there was and has only been one developer/documenter/website maintainer/helpdesk/designer/stunt coder.)

Beyond 6 months and Global uptake

It turned out that Archi was not just being used by the Jisc projects in UK higher education. Professional and student Enterprise Architects everywhere were downloading it. As a result of its early success, 6 months funding turned into 24 months funding, taking me up to December 2012. I have to extend enormous gratitude to Jisc for providing me with the funding to work on Archi for all of that time.

During that overall period I added many more features in response to user feedback posted to the Archi User Forum and received by email. This feedback resulted in Archi’s infamous “Magic Connector” and inspired many other features that contributed to its ease of use and popularity.

archi-sketch

Planning Archi

Feedback was generally positive. Ideas came flooding in from users around the world. News of Archi was spreading fast. Here are some examples of feedback from the first few months of its release (anonymised):

“…first impressions are that it’s a much nicer experience to actually model with… The feeling I get from Archi is that it’s helping me to create shapes, link and position them rather than jumping around dictating how I can work with it. And the models look much nicer too… I think Archi will allow people to investigate EA modelling cost free to see whether it works for them, something that’s not possible at the moment.” – Staffs University, UK.

“It’s a really impressive application and very nicely built on top of Eclipse.” – Healthcare Institute in the Netherlands.

“Archi – nice work – looks very promising – I hope you can find the time and money to keep building it out!” – EA consultant, Australia.

“I’m new to EA world, but Archi 1.1 makes me feel like at home! So easy to use and so exciting…” – Senior Engineer, Russia.

“The most interesting tool to date for Archimate is yours, also because it is based on Eclipse and GEF.” – PhD student from France adding extensions in the Telecom domain.

“Version 1.3 looks great!  We are rolling Archi out to all our architects next week.  The ones who have tried it so far all love it.” – Senior Architect, Insurance company, US.

“It’s a nice alternative… In my first attempts of using the tool I found it to be very useful and promising.” – IT Architect, Delft University of Technology.

I think it’s interesting to note the efficacy of a fast feedback loop between me, as the developer, and an enthusiastic group of users. As the musician Robert Fripp likes to say, it’s important to remain “small, mobile, and intelligent”. Without the constraints of formal processes and methodologies imposed by the parent organisation, I was able to develop the software iteratively and quickly, implementing new features that the users, and I, felt were important. Open beta testing allowed me to fine tune the features as the users suggested.

Archi allows for EA conversations

It was clear then, and still is now, that the availability of Archi as a free tool allowed for a greater degree of sharing and discussion of EA in the UK Higher Education sector, and, indeed in the wider community, both commercially and non-commercially. Archi was the core tool used at various Modelling Bashes at UK Universities, a London King’s College ArchiMate workshop, and many of the discussions in the EA Practice Group meetings revealed that practitioners were sharing models created using Archi.

As I attended more EA Practice Group meetings, overheard discussions, and saw increasing numbers of presentations using screen-shots of Archi models, I saw Archi’s presence growing more and more. Why was this?

That Archi is free and open source is one good reason. Another reason is that it runs on all three main platforms – Mac OS X, Windows, and Linux. But looking at the rich feature-set of some of the major modelling tools tools out there I wonder why anyone would choose Archi. Could it be the pricing model? The bigger tools are great if you’re a large company and can afford the licence, but not so great for the single user, the EA student, the small enterprise, the cash-strapped University.

Archi’s popularity puts a great pressure on me, as the only developer. Users want Archi to support some of the features that these other tools have. For free, of course. They would love to have model repository support, sharing of models, versioning of models, export to this format, import from that format, and so on. Of course, there’s always the get-out clause – “It’s Open Source. Perhaps you’d like to contribute…?”

But whatever the future for Archi, what has been clear to me is that in its existence it has provided very many people with a means to share models and EA conversations that might not otherwise have been possible.

(Go to Part 4)

Archi – an Open Source ArchiMate tool (part 2)

(Continued from Part 1)

Beginnings

As I wrote in Part 1, I had to get something out of the door within the given 6 months of project time funded for Archi. We had said, in the first planned stages, that the deliverable would be a “proof of concept” application, with the hope that we might get additional funding beyond the 6 months if there was enough interest in the project. I was never really interested in creating a “proof of concept” tool, I wanted to deliver a full-blown application, ready for real-world usage.

Some developers are, let’s say, a little unsure of themselves, inclined to conceal their code behind a veil of false modesty. I’m happy to say that I’ve never suffered from this affliction, as I like to get the first few lines of code out there as soon as possible. If it’s junk, I want to know. Maybe I’m naive, or overly enthusiastic, or maybe it’s because, as the character of Mister Wolf in the film Pulp Fiction says, “I solve problems”.

If I’m writing a desktop application, such as Archi, I like to start straight away by creating an empty application window with the App’s title in the top bar, an icon, a basic menu and an “About” dialog box declaring me as the author (to take the blame, not the credit). That’s it. This only takes a few hours to put together, but it means that you have an App. It doesn’t do anything except open, close and show the “About” box, but you have a freakin’ App. It’s like creating a frame for a picture, or an outline for a novel. On day 1 you can launch your App and you can show it to people. It’s a tangible thing. This is really important if you want to encourage interest in your endeavour, and convince people that you just might be able to do the impossible. Also, this is Open Source software funded by public money, so transparency is key.

After the initial code was written, I created a project at SourceForge and committed the code. It was a CVS repository then, now no longer visible since the transition to Git a year later.

Frameworks

Choosing a modelling and graphical framework was the next task. At the time, I could already hack something in Eclipse’s Graphical Eclipse Framework (GEF) which would take care of the boxes and lines, and I could use the Eclipse Modelling Framework (EMF) for the model, persistence, and model notifications. Additionally, there is the Graphical Modelling Framework (GMF) which combines the two frameworks but this turned out to generate too much Voodoo Code.

modelling wtf

The Eclipse Modelling World

Voodoo Code is a term I use for frameworks that generate code and artifacts based on a given set of user-provided meta-models and input by some mysterious and opaque process. Something very, very clever is going on in that Voodoo, but you sure as hell don’t know what it is. Many lines of code are automagically generated, but you don’t know how to modify them, or what might break if you do. I have to confess to being horribly confused by GMF, I feel scarily not in control; and of course there’s the old problem of the lack of documentation in the Eclipse eco-system (don’t get me started on that subject). And I only had 6 months to work with. It was like this Dilbert cartoon:

dilbert

Frameworks

I went with the “old school” option – a combination of EMF to create the model and persistence framework, and GEF to handle the drawing graphics, and I would hand code the “glue” between the two frameworks. The cross-platform, Java-based, Eclipse framework could handle all the windows, menus and other GUI requirements. At least this way I could understand and maintain the code without feeling that it was all sinking away from under my feet. I should say that the EMF does in fact generate code, but it’s boiler-plate code, easily modifiable and very easy to update (and EMF has great documentation and support). Eclipse did a great job with that framework. Not so sure about GMF, though. A colleague once remarked that he wished GMF could be “un-invented”.

I spent the next two months developing a basic EMF meta-model for the ArchiMate model and the Application model, and linking this to the GEF to draw the boxes and lines, and battling with the Eclipse framework in order to beat it all into some coherent shape. At one painful point in the development process I grew doubtful, abandoned EMF completely, and spent the next three days and nights coding an alternative. On the fourth day I realised that I had effectively re-written EMF, although in a half-baked manner. The following day, I put it all back again, and really appreciated how well EMF has been devised. I wasn’t using Git version control in the early development phase, I was using CVS. If I had been using Git, I could have created any number of alternative, experimental branches with ease.

Go to Part 3

Archi – an Open Source ArchiMate tool (part 1)

Archi is a free, open source, and cross-platform desktop application for creating models using the ArchiMate modelling language that I developed between 2010 and now.

ArchiMate

What is ArchiMate? I suppose you might say that it’s a bit like UML or BPMN, except that it addresses a higher level of business modelling abstraction, the domain that interests so-called “Enterprise Architects”. For me, I like to simplify this and say that ArchiMate is just more “boxes and lines”, albeit with a special meaning.

archimate_meta

ArchiMate Metamodel

I suspect that ArchiMate and its associated framework, TOGAF, are not widely known outside of the arcane world of Enterprise Architecture and its cohort, and so the tools that its practitioners employ are rather specialist. Consequently, these tools tend to be somewhat expensive as they are aimed at mid to larger organisations, and sold using the “enterprise” level of subscription model. This is fine for those organisations that can afford it (banks, insurance companies, manufacturers), but can prohibit the individual user or student who may just want to learn ArchiMate, or at least experiment with it.

Background

In 2009 I was working for an organisation within an organisation within an organisation (perhaps a dis-organisation?). It turned out at the time that some UK universities had started to take their first steps into this brave new world of Enterprise Architecture and ArchiMate as part of a Jisc funded initiative aimed at improving services and processes in the UK higher education sector. For many participants, this was an entirely new domain, and committing to a particular proprietary toolset to support the project was considered to be risky. Some universities had already bought a single licence for one of the existing ArchiMate tools, whilst others had started to use Microsoft’s Visio drawing tool. For larger businesses the cost of these tools and support might be no big deal, but for cash-strapped UK universities it was a serious concern, especially as they were only doing this as part of a special programme and didn’t want to incur any recurring costs if it didn’t work out. The absence of a standard export format also raised concerns of the possible danger of proprietary lock-in.

Jisc proposed that additional funding could pay for the development of an open source ArchiMate “proof-of-concept” modelling tool that could be used by those institutions as a “taster” of ArchiMate before committing to a full-blown solution, and also provide a means to make an intervention in promoting an open exchange format for ArchiMate. The proposal was for:

…the creation of an OSS tool oriented towards those making their first steps with Archimate and with functionality somewhere between template-driven drawing tools like Visio and “enterprise class” tools which would fill a space in the market and provide a platform for implementing a standard export.

Given my previous development experience with Eclipse and some familiarity with Eclipse’s modelling framework (EMF) I was given 6 months to develop such a basic ArchiMate modelling tool.

I like a challenge.

6 months for one developer to create an open source, cross-platform tool for modelling an unknown (to me, at the time) visual language. I’m not sure if you’d consider this ample provision or not. I’ll just say that, in retrospect, 10-12 hours a day of coding for 6 months carries health risks.

I set to work in early 2010, reading up on the ArchiMate specification (dry and boring when read with nothing concrete to hang it on) as best as I could given that I had never been involved with Enterprise Architecture. A first draft plan was agreed, and implementation would be basic given the limited time-scale.

archi
Go to Part 2

We are all Journalists

It seems that the US Senate wants to redefine the term “journalist” with the so-called “Shield Law”.

http://blogs.wsj.com/washwire/2013/09/12/senate-panel-approves-media-shield-law/

Of course, this means excluding Julian Assange as a “journalist”:


http://www.theatlanticwire.com/politics/2013/09/terrorists-and-julian-assange-arent-considered-journalists-senate/69355/

http://www.huffingtonpost.com/2013/09/12/media-shield-law_n_3912955.html?utm_hp_ref=politics&ir=Politics

Whatever they say, with the power of the internet at our disposal, we are all journalists.

we are all journalists