I recently worked on a proof of concept mobile application for an insurance company. It was simply designed as a tool for sales to demonstrate how a potential concept could work.
The statement of work seemed to be reasonable, a week to improve some functionality and change some branding. It also included updating the dependencies of the project and upgrading it to work with latest tool set.
It really seemed like a reasonable project until I was given the source code. I realized that what I had in hand was production quality code with hundreds of libraries included. I could barely understand the workflow of how the code lead to functionality, it seemed like sorcery was being used to generate it. I've worked on a dozen of mobile applications and it was generally easy to understand how they worked.
Obviously, this 3 year old project wouldn't compile with the latest tool set. I thought it would be an easy task to simply bring up the libraries to their latest version, but a ton of compiler errors were thrown. Why? The code heavily relied on paradigms from the older libraries and the newer ones have changed workflows completely.
I realized that updating the application would require major refactoring which wouldn't fit within the tight deadline. I won't give too many details as work is supposed to be confidential, but it was a very simple app with a few screens and extremely basic functionality.
At that point, I decided that I would rewrite the application from scratch. What took a team several months to do I was confident that I could do it in one day. However, I wrote very simple and easy to understand code. It's a proof of concept, a prototype. The source code is supposed to be disposable once the company decides to turn the PoC into a production quality application.
In one day, I had the prototype working with the same functionality, actually more, than the original version. My goal was very different, it was a PoC, not production software, it's supposed to be a prototype. One day's worth of work is not costly to throw out, but spending on several employees to do the same thing, but with way more complicated code is way more costly and even more when it comes time to maintain it.
Even production applications can be overengineered. Code can be very clever but an impossible mess to actually understand. Most developers don't realize that code is easier to write than to read. In several years, a simple bug fix will break the application because you can't remember how the asynchronous event system worked when it could have been a simple method call in a seperate thread.
Code is supposed to be of the same scope of the application, not more. Annotations, lambda expressions and so on are tools to help you write more readable code but only when it stays reasonable. A super clever implementation of lambda expression that spans the entire screen is much worse than a simple for loop which is what you really needed.
New developers want to show how clever they are with complicated code, however it doesn't impress anyone because no one understands it. As I progressed throughout my career, I realized that very simple code is way more elegant than clever black magic. As a result, I ended up with more maintainable code that I could come back to years later when it needed a simple bug fix and I was confident that it wouldn't break anything else.
My belief is that code should be as simple as reading an English article. Only a one pass reading should give you an idea on what's going on. If you need to reread the code several times to understand it, it's a bad sign.
When you do need to be clever because it's the only choice, it better be documented with plentiful of comments, that explain why and not how the code was designed that way. Whatever is needed whether it's diagrams, a separate document or even a video. The point is that the next developer understands it right away.
If you can recite the code and it sounds like English sentences, you're on the right track.