Welcome!

Java IoT Authors: Carmen Gonzalez, Yeshim Deniz, Elizabeth White, Pat Romanski, Liz McMillan

Related Topics: Java IoT

Java IoT: Article

Let's Do Better

Let's Do Better

There's a J2EE tie-in. I promise.

A fellow user mentioned something the other day about using libraries in Java. He said, and I paraphrase, that he simply didn't feel comfortable using a library if it couldn't be explained in one page. For the sake of argument, I'll assume he didn't mean one 400K page.

I'm not sure I wholly agree with his statement, but his point is well taken. When I look for a tool, I want that tool to have a very clear purpose and documentation. A name should be an easily associated mnemonic, perhaps a direct tie-in to purpose, and the documentation should allow the user to quickly get a sense of not only what the product does, but how and why, too.

Some examples of good product names, in my opinion: EXML, RSSLibJ, commons-httpclient. Some bad ones: commons-digester, maven, blissed. I'm not saying the ones named well are great products; I have my reservations about them, even the one I co-authored. Nor am I saying the products whose names I dislike are not good products: I'm simply saying that their names don't help you associate the products with what they're for.

I think virtually everyone understands the problem of good documentation: you'd be hard-pressed to find any programmer who hasn't gone to some project's documentation, read for a while, and come away scratching her head with no clearer picture than she had before. Maybe that's happened with popular projects - I know that some of my own general-purpose projects are still "blessed" with obscure docs.

I'm hardly exempt from the problem of documentation. I'm a fairly abstract thinker in a lot of ways, and a "big thinker," so I have a tendency to solve problems in abstract ways, making things harder to explain. It's happened a number of times in my career that I've intuitively architected a solution and been unable to explain it to the teams around me... until later, when the problems my solution addressed manifested themselves. (True story: one team refused to take my solution as anything more than the rantings of a mad hatter, and chose to use a simpler, more straightforward architecture. Months later, when the localization problem I was trying to solve became apparent, they - and I - realized that I'd been on the right track all along, and we ended up going back to the plan I'd suggested first. I've never had a deserved reputation as a great communicator.)

My difficulties are directly related to my mode of thought because I tend to be a bit scattered and draw technical material from a lot of sources related to the humanities. I can shrug and say, with a light sprinkling of seriousness, that I'm an artiste and can't be held to reasonable expectations. That said, I don't see that same scattershot approach in every project, so why do so many of them have poor or unclear documentation? We're nominally engineers; why can't we approach our solutions from an engineer's cut-and-dry viewpoint and say, "Here's the problem; here's a solution; here's why this solution was chosen; here's how to make it go"?

I don't have a clear answer. If I did, I'm sure my own wider-scoped projects would have better documentation. I can just use that programmer's statement about a one-page document as a guide limning my path, and as a measuring stick that I can hold my own documents up to. Is the document as short as it can be? Does the document have a premise? Is it directly answering that premise? If I was reading it without foreknowledge of the subject matter, would I be able to understand what the document was trying to say? Would it contain useful references to other documents to give me the bits outside of the basic premise?

I know that I sound like a professor of language, asking those who write to approach the task as if it were a craft. I imagine many are shuddering with bad memories of college essays, thinking you'd gotten away from crafting term papers and theses. Well, you have - I don't ask anyone to write a doctorate-level paper when all you are trying to do is tell someone how to write a Webwork interceptor. However, the basic skills still apply - who, what, when, where, why, and how. Without these being at the very least addressed and discarded, a document will always sound vaguely unfocused, and that's torture for your readers.

By now, you're reading this wondering why a Java Enterprise editor is lecturing on basic documentation skills. I promised a tie-in, and here it is: recently, Tod Nielsen (executive VP of BEA) wrote a missive I disagreed with about the future of J2EE being predicated on clarity and simplicity. I saw his point, but I think he's reacting to the lack of effective writing on the industry's part. We write complex systems and don't bother to explain them in simple ways, so we're left perceiving their complexity, and people who aren't interested in complexity for complexity's sake just don't care. Donald Knuth imagined literate programs as programs that you would read, sitting by a fire with a glass of something enjoyable handy. If architectures were designed with this kind of perusal in mind, think of the future time spent maintaining them: it'd be a joy, comparatively, and Mr. Nielsen's plea for a simpler API would sit unneeded.

We need to work on our communications, all of them. Our systems, regardless of their underpinnings, need to be explained in simple, clear terms. Anything less dooms us to the amateurism of which our industrial competitors accuse us.

Let's do better.

More Stories By Joseph Ottinger

I am a software evangelist for GigaSpaces technologies, as well as a writer and musician. I've been the editor-in-chief of Java Developer's Journal and TheServerSide.

GigaSpaces Technologies is a leading provider of a new generation of application platforms for Java and .Net environments that offer an alternative to traditional application-servers. The company's eXtreme Application Platform (XAP) is a high-end application server, designed to meet the most demanding business requirements in a cost-effective manner. It is the only product that provides a complete middleware solution on a single, scalable platform. XAP is trusted by Fortune 100 companies, which leverage it as a strategic solution that enhances efficiency and agility across the IT organization.

Comments (0)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.


@ThingsExpo Stories
The 21st International Cloud Expo has announced that its Call for Papers is open. Cloud Expo, to be held October 31 - November 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA, brings together Cloud Computing, Big Data, Internet of Things, DevOps, Digital Transformation, Machine Learning and WebRTC to one location. With cloud computing driving a higher percentage of enterprise IT budgets every year, it becomes increasingly important to plant your flag in this fast-expanding busin...
A strange thing is happening along the way to the Internet of Things, namely far too many devices to work with and manage. It has become clear that we'll need much higher efficiency user experiences that can allow us to more easily and scalably work with the thousands of devices that will soon be in each of our lives. Enter the conversational interface revolution, combining bots we can literally talk with, gesture to, and even direct with our thoughts, with embedded artificial intelligence, whic...
SYS-CON Events announced today that Cloudistics, an on-premises cloud computing company, has been named “Bronze Sponsor” of SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Cloudistics delivers a complete public cloud experience with composable on-premises infrastructures to medium and large enterprises. Its software-defined technology natively converges network, storage, compute, virtualization, and management into a ...
Every successful software product evolves from an idea to an enterprise system. Notably, the same way is passed by the product owner's company. In his session at 20th Cloud Expo, Oleg Lola, CEO of MobiDev, will provide a generalized overview of the evolution of a software product, the product owner, the needs that arise at various stages of this process, and the value brought by a software development partner to the product owner as a response to these needs.
New competitors, disruptive technologies, and growing expectations are pushing every business to both adopt and deliver new digital services. This ‘Digital Transformation’ demands rapid delivery and continuous iteration of new competitive services via multiple channels, which in turn demands new service delivery techniques – including DevOps. In this power panel at @DevOpsSummit 20th Cloud Expo, moderated by DevOps Conference Co-Chair Andi Mann, panelists will examine how DevOps helps to meet th...
Most technology leaders, contemporary and from the hardware era, are reshaping their businesses to do software in the hope of capturing value in IoT. Although IoT is relatively new in the market, it has already gone through many promotional terms such as IoE, IoX, SDX, Edge/Fog, Mist Compute, etc. Ultimately, irrespective of the name, it is about deriving value from independent software assets participating in an ecosystem as one comprehensive solution.
SYS-CON Events announced today that EARP will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. "We are a software house, so we perfectly understand challenges that other software houses face in their projects. We can augment a team, that will work with the same standards and processes as our partners' internal teams. Our teams will deliver the same quality within the required time and budget just as our partn...
SYS-CON Events announced today that delaPlex will exhibit at SYS-CON's @ThingsExpo, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. delaPlex pioneered Software Development as a Service (SDaaS), which provides scalable resources to build, test, and deploy software. It’s a fast and more reliable way to develop a new product or expand your in-house team.
SYS-CON Events announced today that Tappest will exhibit MooseFS at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. MooseFS is a breakthrough concept in the storage industry. It allows you to secure stored data with either duplication or erasure coding using any server. The newest – 4.0 version of the software enables users to maintain the redundancy level with even 50% less hard drive space required. The software func...
SYS-CON Events announced today that A&I Solutions has been named “Bronze Sponsor” of SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Founded in 1999, A&I Solutions is a leading information technology (IT) software and services provider focusing on best-in-class enterprise solutions. By partnering with industry leaders in technology, A&I assures customers high performance levels across all IT environments including: mai...
With major technology companies and startups seriously embracing Cloud strategies, now is the perfect time to attend @CloudExpo | @ThingsExpo, June 6-8, 2017, at the Javits Center in New York City, NY and October 31 - November 2, 2017, Santa Clara Convention Center, CA. Learn what is going on, contribute to the discussions, and ensure that your enterprise is on the right path to Digital Transformation.
In his keynote at @ThingsExpo, Chris Matthieu, Director of IoT Engineering at Citrix and co-founder and CTO of Octoblu, focused on building an IoT platform and company. He provided a behind-the-scenes look at Octoblu’s platform, business, and pivots along the way (including the Citrix acquisition of Octoblu).
SYS-CON Events announced today that Systena America will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Systena Group has been in business for various software development and verification in Japan, US, ASEAN, and China by utilizing the knowledge we gained from all types of device development for various industries including smartphones (Android/iOS), wireless communication, security technology and IoT serv...
SYS-CON Events announced today that Outscale will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Outscale's technology makes an automated and adaptable Cloud available to businesses, supporting them in the most complex IT projects while controlling their operational aspects. You boost your IT infrastructure's reactivity, with request responses that only take a few seconds.
DevOps at Cloud Expo – being held October 31 - November 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA – announces that its Call for Papers is open. Born out of proven success in agile development, cloud computing, and process automation, DevOps is a macro trend you cannot afford to miss. From showcase success stories from early adopters and web-scale businesses, DevOps is expanding to organizations of all sizes, including the world's largest enterprises – and delivering real r...
SYS-CON Events announced today that CollabNet, a global leader in enterprise software development, release automation and DevOps solutions, will be a Bronze Sponsor of SYS-CON's 20th International Cloud Expo®, taking place from June 6-8, 2017, at the Javits Center in New York City, NY. CollabNet offers a broad range of solutions with the mission of helping modern organizations deliver quality software at speed. The company’s latest innovation, the DevOps Lifecycle Manager (DLM), supports Value S...
SYS-CON Events announced today that Enzu will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY, and the 21st International Cloud Expo®, which will take place October 31-November 2, 2017, at the Santa Clara Convention Center in Santa Clara, CA. Enzu’s mission is to be the leading provider of enterprise cloud solutions worldwide. Enzu enables online businesses to use its IT infrastructure to their competitive ad...
SYS-CON Events announced today that Peak 10, Inc., a national IT infrastructure and cloud services provider, will exhibit at SYS-CON's 20th International Cloud Expo®, which will take place on June 6-8, 2017, at the Javits Center in New York City, NY. Peak 10 provides reliable, tailored data center and network services, cloud and managed services. Its solutions are designed to scale and adapt to customers’ changing business needs, enabling them to lower costs, improve performance and focus intern...
Everywhere we turn in our industry we can find strong opinions about the direction, type and nature of cloud’s impact on computing and business. Another word that is used in every context in our industry is “hybrid.” In his session at 20th Cloud Expo, Alvaro Gonzalez, Director of Technical, Partner and Field Marketing at Peak 10, will use a combination of a few conceptual props and some research recently commissioned by Peak 10 to offer a real-world consideration of how the various categories of...
In order to meet the rapidly changing demands of today’s customers, companies are continually forced to redefine their business strategies in order to meet these needs, stay relevant and continue to see profitable growth. IoT deployment and development is integral in this transformation, and today businesses are increasingly seeing the value of investing their resources into IoT deployments. These technologies are able increase ROI through projects such as connecting supply chains or enabling sm...