Documentation. Hardly anybody wants to write it, but it is one of the most important deliverables in a software project. Without documentation, it becomes very difficult to understand why things were done the way they were and if the project is operating as expected. 

I have joined several projects where there was a lack of documentation. Sometimes you’ll be blessed with comments, but, in my experience, the only comments to be found are commented-out code. In Oracle SOA/BPM projects and Mulesoft projects, documentation is even rarer than in other projects. I’m not perfect – I’ve contributed to this problem as well. I’ve completed some code for a project and then, a month later, had to come back to the same code and figure out what the code is supposed to be doing in order to make modifications. Many developers will tell you the “code is self-documenting”, but the code doesn’t show you the intent. In order to ascertain intent, one must consult documentation or requirements, and it isn’t always clear which code fulfills which requirements.

Commented Code

 

 

 

 

 

We are all better than this!

 

Mulesoft Notes FieldOracle Documentation

Save your colleagues and yourself some unnecessary time and document your code. It is possible to figure out what a chunk of code is supposed to do, but it takes much less time to read a sentence that says what the code is meant to do. The comment doesn’t have to be extremely detailed, it just needs to express the general idea. Put a comment in your Java code, fill in the Description field in your BPMN or BPEL activities, or write something in that Notes attribute on your Mulesoft message processors. Don’t leave the comments blank – you will thank yourself later!

Join the Conversation

About the Author