Sounds like a simple question, but is it?
Today I was helping out on a second project from the stone age. It’s at least a decade old and still running and maintained. After checking out, I dared to run a mvn clean install and guess what happened?
As much as I love Java, yeah it is still one of my languages of choice after 2 decades, one thing that feels pretty annoying all the time is adhering to the Java Bean convention and thus providing getter and setter and sometimes a few others. The convention itself makes sense and a lot of the libs in the Java world require it. Yet, it never made it into the compiler and automatically provide it. Kotlin does it, why not Java?
There’s a confluence for the project from stone age I am helping out. Its aim is to provide the documentation for the project. Unfortunately, it does not have a clear focus for whom it is written.
Yep, a documentation has an audience - the stakeholders. Depending on the audience, it contains slightly different information, e.g. third-party devs connecting to the system want to know how to do just that and how they can map their business use cases to the systems API; on the other hand, the internal devs are probably not interested in such details as they care for their business use cases. Same goes when the audience is non-dev too.
Sandeep joins the discussion and comes up with a question regarding out-of-date documentation.
Yesterday’s topic and Alejandro’s reply lead me to another type of documentation. The out-of-code docs. Everything we document about our system which is not in the code or at least close to the code, that can be diagrams, wikis, word docs, whatever.
Yesterday I talked about a case of Javadoc gone wrong. Reader Alejandro wrote in and thinks I am missing the main problem here because it is the code and not the Javadoc. I’d like to discuss that a bit further.
Today I am presenting you a case of Javadoc gone wrong; an actual live one, just saw it today, live and in color, in the project from the stone age.
I know, many people do hate Mondays. Personally, I did too. But now, it’s the opposite. I love them.
One topic I’ve never found a perfect solution for is “how to document the architecture?”.