No documentation – a coding error?


, , , , ,

I came across this tweet from Oracle Developers (Oracle Developers Tweet) which picked up on a post from the NoBugsProject about common errors with the use of exceptions. One of the first errors the article described is one of my pet hates – the use of standard exceptions for application specific errors.

This took me onto one of my other pet hates – code without any documentation. I’m not advocating the days of waterfall Development where reams of documentation had to be produced before a single line of Code was written. In fact this is in my option worse than nothing as the docs would often not match the coded reality. But I absolutely agree with the agile manifesto statement:

We value working code over documentation

This doesn’t say no documentation, despite the fact that I have encountered more times than I care to recall the use of this statement to justify not documenting code. So what is the right balance?

We want to save effort from Code reviews and get clean code by using static code analysis but it doesn’t have the ability to apply smarts as what needs documenting? Pair programming is rarely practised, and there is plenty of psychology about group behaviour that can undermine documentation in a pair working approach effort. So what is the answer?

Well, I’ve always applied a couple of personal rules of thumb that can be measured with static code analysis particularly if you use conventional documentation tags. The rules are:

  • Interfaces warrant an interface level description of the interface purpose. It’s always helpful to describe/illustrate with use example. This is code equivalent to a good API Blueprint or swagger doc.
  • Provide a class level description of what the class is for – if it is a DAO then just say what the entity is.
  • If a class is part of a pattern, name the pattern. This is most important when relating to supporting a composite or solution pattern. Remember there will always situations where a newbie will get asked to extend or change your code, help them. Remember not every developer is as experienced or clever as you. If in doubt, give your code to someone who doesn’t know what you’re working on and ask them to explain what your code is doing and why. I had once, had to create a JDBC abstraction layer as we needed to support multiple databases. But if you know JDBC you’ll be aware of there are some subtle but important differences in implementation of connectors. I took the time to explain it in the interface header. I know a couple of developers appreciated the investment of 5 minutes.
  • If you have a function that has a code analytics score such as cyclometeric then describe the function. Use the comment to convey why the high score is justifiable.
  • If the code has specific dependencies or has to perform in a very specific sequence a short comment will help, and anyone going through refactoring code.

With these guidelines it becomes possible to then use javadoc tools to generate your documentation. It doesn’t require you to go find a word document or a wiki page to update the documentation. Of course then reviewing the generated documentation will soon help you finesse the process of documenting in a manner that is whilst light also supports readability without needing the code.

For those, who still disagree I would say …

  • Do you want to be maintaining and updating the same code for the rest of your career to meet new minor changes etc?
  • Not everyone is a great coder like you, do you want someone less capable who may have to make a change messing up your elegant code?
  • Sooner or later someone will ask you to fix or enhance some code that in your eyes is a chaotic unintelligible mess, I’m sure you’d appreciate some comments that will help you understand what the developer was trying to do? We can’t expect those not so good at the craft to document if the best of us are not prepared to do so.

If you don’t agree, or have found different approaches that ensure enough accurate documentation, please share.

hAPI times – latest contribution to Oracle Scene


, , , , , ,

My latest contribution to the Oracle Scene journal is available at here. This article looks at the evolution of APIs, and a look at modern API Gateway capabilities. The article uses an analogy to explian the capabilities in a non-techie way.

In addition to my article the team I’m part of get a mention for their wins at this years Partner of the Year awards.

Continue On PC


, , ,

send-to-pcMicrosoft have developed a feature called ‘Continue on PC‘ which in principle is a great step which allows you to send content from your IOS or Android phone.  In many respects the idea is like the IOS Airdrop in capability.  This is to say you could start reading a web page on your mobile device and then send the page to your desktop.

A great idea, and when it works its a reasonable experience. There are some real issues though. The first grouch is that when sharing a web page, the content is presented on the desktop using Microsoft Edge, not your preferred browser.

More disappointing is that install the solution the device has to be able to receive a text message. As a result unless your tablet has mobile connection it can’t be configured to use the solution.

I’ll be presenting at UKOUG Conference with …


, , , , , , ,

I will be presenting at the UKOUG Conference this year as an Oracle Ace and Snr Consultant from a award winning Partner of the Year. I’ll be speaking about:

  • ICS (now part of Oracle Integration Cloud)
  • Microservices and WebLogic
  • Oracle Messaging Cloud Service

I also have colleagues from Capgemini covering IaaS and SaaS among other things. I hope that we see you in Birmingham. Full details of my sessions :

Integration Cloud Service (ICS) Customer use Cases an Insight Into why ICS

04/12/2017 09:00 &

05/12/2017 09:00

In this session the presenters will talk about several applications of Integration Cloud Service (ICS) with customers from Capgemini. Whilst presenting the use cases, the reasoning for adopting ICS over other integration options will be explained and some of the design considerations that had to be addressed in the application of ICS. Whilst looking at the example cases, factors involved in deciding which iPaaS offering to adopt based on needs.
This session will be presented by Phil Wilkins one of the authors of the book Implementing Oracle Integration Cloud Service and supporting blog.

Microservices in a Monolith World

04/12/2017 15:25

Whilst microservices are mainstream thinking, many organisations make significant long term investments in application containers such as WebLogic and can be resistant to moving on from such investments. So how do we realise the microservice thinking with such constraints? This presentation looks at several approaches that can allow us to leverage microservice thinking without sacrificing the existing investment.

Why Should I Consider Oracle Messaging Cloud Service as an Integration Solution?

04/12/2017 17:55

Oracle Messaging Cloud Service is an often-overlooked service in the family of iPaaS options, but why? So, what makes it worth considering and makes it more contemporary than JMS with Java Cloud Service? This presentation will look at what differentiates MCS from JCS and Event Hub and others and does it offer that makes it distinct and worthwhile option?

Equifax Security Breach – Time for a Change In Mindset



I was reading a blog post from the Cloud Security Alliance (here) about the on-going mess and disinformation around Equifax’s security breach.

The article makes a very good point. Sadly Security is seen as just a cost, and whilst people have that mindset we will see decisions being made that favours ‘high share value now’ over long time assurance of sensitive data which means that ‘now value doesnt nose dive’.

The article goes on to show the approximate cost to the US public of the breach. But if we can quantify the costs, can we not quantify the value of protection?

Even with today’s legislation in many countries it is a legal obligation to disclose the details of a security breach. The only problem here, is ignorance is bliss, if I don’t know I’m being compromised then nothing to report. The blog post also points out that often the only time security investment is recognised is, and often that information doesn’t propergate within an organisation. This got me to thinking why can’t companies also disclose how many attempts on their security have been mitigated on in the same way companies have to declare profit and loss.

It could produce some interesting information, as you could compare data from different companies of similar profile. When plotting the data, any outliers suggest something maybe wrong. But it would give consumers a means to decide do they trust their data with X over Y when they get a chance to influence the decision.  But we’re now moving into the territory where security is becoming a positive measure.  If nothing else it may engender an ‘arms war’ of who has the best protection.

As with all things, they way you measure something influences behaviour. This sort of measurement may encourage companies to invest in more ‘white hat’ attacks. That’s no bad thing as if a white hat attack suceeds – the vulnerability has been found.

The interesting thing is that, the article points out that Equifax and other large companies that have been breached have been certified as ISO 9001 compliant, PCI DSS compliant and so on. The issue here is, that these accreditations have a strong emphasis on process and policy, and are down to the auditor spotting non-compliance. In a large organisation the opportunity to steer the auditor towards what is good exists. But more importantly, process requires people to know and follow it. Following process and being prepared to uphold the processes requires an organizational culture that genders its adherence. I can have a rulebook as big as the Encyclopedia Britannica but if my boss, and his boss apply constant pressure to say we have to deliver and there is no repercutions to bending the rules – well then I’m going to start bending.

Leaders like Gray understand the value of an organization’s culture. This can be defined as the set of deeply embedded, self-reinforcing behaviors, beliefs, and mind-sets that determine “how we do things around here.” People within an organizational culture share a tacit understanding of the way the world works, their place in it, the informal and formal dimensions of their workplace, and the value of their actions. Though it seems intangible, the culture has a substantial influence on everyday actions and on performance.

This brings us back to the idea – hard data on the execution (not that i have a process for execution) will give strong indications of compliance. This kind of data is difficult to fudge and with a good sample set, then fudges  are more likely to stand out.

Practical? I don’t know, but worth exploring? If we are to change security thinking then yes.

APIs and OMESA video


, , , , , , , , ,

If you like seeing or hearing people like Arturo Viveros, Luis Weir and myself (not for me  :-0 ) discussing (Open Modern Enterprise Software Architecture) and APIs then you’ll like the following video, recorded with Bob Rhubart of Oracle Developer Community ArchBeat fame at Oracle Open World 2017.

ODC Appreciation Day : Apiary Editor


, , , , , ,

This post is my contribution to the Oracle Developer Community (ODC) Appreciation Day. The idea of the event is best explained by Oracle Base – go here.

The Apiary Editor has to count as a pretty new entry into the possible features that could be considered with Apiary only coming into the Oracle family in the last year. Apiary as a solution provides a platform by which modern REST based APIs can be designed, documented and simulated. Apiary supports the API First design philosophy (more here) using API Blueprint notation or Swagger (now known as Open API).

The feature I want to focus on is the Apiary Editor itself (shown below), particularly when working with the API Blueprint.  The beauty of the solution is that as the documentation or API syntax is edited in the editing side (left)  the API definition/documentation immediately appears on the presentation side of the editor  (right) making it easy both see the technical specificastion and how the information is initially presented to a potential API user. This makes it really easy to understand the clarity of what is being communicated which is one of the important aspects of an API definition and API first.

Whilst Agile development states ‘prefer working code over documentation’ this provides agility as you can develop the API definition and allow people to develop against the contract we can still easily deliver quality API descriptions with sufficient information to make it understandable to a 3rd party.

Becoming an Oracle Ace



On Friday 29th September, 2 days before the commencement of Oracle’s most important event of the year – OpenWorld whilst attending the Oracle Partner Advisory Council I received word that I had been promoted to a full Oracle Ace.

For those not working in the Oracle ecosystem this is comparable to being confirmed as a Microsoft MVP, a SAP Mentor or Java Champion. These schemes recognize contributions made by non employees to the community and the parent company itself. These contributions range across public speaking, articles for journals, helping through the various community sites and blogging among others. Hoist the accreditation is based on contribution, to be a successful contributor you need to be deeply knowledgable in your specialisms.

The importance of the Ace recognition is important for my employer (Capgemini) and for myself for different reasons. For an employer the association of expertise can be a key value propositions, and some Oracle partners actually use the number of Aces they employee as a key part of their differentiator and market proposition. Secondly, being out communicating with the community raises brand awareness increasing the chances of both sales but also make the company more attractive as a potential employer. Finally, through participating with in events you get to know product managers and other scenario Oracle people. As a result, when additional support and engagement is needed you have the contacts to draw on. But is not just help, the opportunity to contribute to product development exists. In many respects this can become a virtuous circle – the more you do the more opportunities open up, the more you can do.

For me personally the Ace programme is a very friendly embracing community that whilst can be commercially competitive is very mutually supportive. This combined with the fact that the culture of sharing knowledge is actively encouraged, supported and acknowledgement of those efforts is always satisfying.

In the middleware space there are less than 50 active Oracle Aces of all grades globally. Four of those are in the UK  Luis Weir (Ace Director – Capgemini), Simon Haslam (Ace Director – eProseed), Mark Simpson (Ace Director – Griffiths Waite) and myself. I am also fortunate enough to count all three as friends.

Presentations from Oracle Open World


, , , , , , , ,

With Oracle Open World 2017 over the ICS presentation is available at – Oracle integration cloud service (ICS) best practices learned from the field (OOW17)

We saw a lot of exciting new features and capabilities coming from Oracle in the ICS space. So keep an eye on the site as we publish new articles.

The API Platform presentation that was co-presented with Luis Weir is here…