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?”.
I’ve recently started a Spring Boot local meetup here in Frankfurt. We already had a great start with a talk about “Moving from Java to Kotlin with Spring Boot”. It was great to get first-hand experience from devs who already work with the Kotlin-Spring Boot combination.
DRY is another principle and commonly riding along the other two. DRY stands for don’t repeat yourself; meaning “Every piece of knowledge must have a single, unambiguous, authoritative representation within a system” aka writing that piece of code, schema, whatever once for the entire system and re-use. Don’t duplicate code if it’s logically related.
Another true principle of our craft is YAGNI - You ain’t gonna need it.
One of the key principles we devs violate way too often. We devs love complex systems too much.
For those unfamiliar with the acronym and principles. It stands for Keep it simple, stupid.
I am a firm believer that anyone should have a side-project. It does not matter if it is for pure learning purposes, fun or with the goal of making money.