Undici

Documentation.

This morning was spent assessing my Java TTT through the process of building an UML diagram. As it stands this is not the final version, since I neglected to add methods to each of the listed classes. Even without that though, you can see at a glance how messy the diagram looks, which is a strong sign that my classes are a bit too dependent on each other.

I will continue to work on this diagram a little bit tomorrow and post the updated version. It is a representation of my project as it currently stands, it will be interesting to see how this diagram changes by the end of the project.

The afternoon was spent dealing with a story for streamlining the usage of my TTT on other peoples laptops. I had hoped it would be a simple process, and to be fair it only took half a day, but in hindsight I think an hour might have been more appropriate if only the documentation had been better.

It’s difficult to judge documentation sometimes, because everyone approaches it with a different aim in mind. So for my usage it wasn’t good enough, but perhaps for someone else it would be. That said, it was surprising to me that some of the basics were difficult to find, the Gradle Application plugin for example, is meant to allow you to “run” your program through just two lines in your build file:

apply plugin: 'application'

mainClassName = "com.company.Main"

Nowhere in the documentation could I find notice that the standard in and out are overwritten when doing so. So, the program would run perfectly if executed through IntelliJ and through the compiled jar file, but would raise exceptions when using gradle run. After sometime spent trying to determine what the issue actually was, I found an answer on Stackoverflow.

Add this to your build.gradle

run {
    standardInput = System.in
}

I’ve never had to write much documentation outside of accompanying an API, however, I can see how for something as big as gradle it could be a daunting process. Perhaps the solution lies in monitoring stackoverflow for questions and determining where the holes are in your documentation.