We software developers write source code every day, or we change or fix it. What we do wrong all the time are basically three things:
These weaknesses do not worsen things in terms of weeks or months, they do not diminish our short-termed success. But at some point they then strike fundamentally in a way that the code will be thrown away, including all knowledge in it. Even when it was working code.
This is about Copy & Paste programming. Every beginner does it, and by that way he/she quickly succeeds in creating modules that actually work. The pain then starts when changes and fixes have to be done, and it turns out that concepts and bugs have been multiplied by Copy & Paste, thus the new concepts and fixes must be applied multiple times.
Moreover, repeats are boring. Who wants to read texts that are full of repeats? You get tired of always seeing the same names and identifiers. You have deja-vu all the time. You generate errors by confusing things, because they all are so similar. Everything seems to be unnecessarily blown up, and you don't take it seriously any more.
Repeats can be everywhere, in method names, variable names, class names, in code sections, even classes and whole packages are copied from each other.
Try to do it once-and-only-once. Stick to the Agile DRY principle. Try to remove repeats wherever you see them. Then everything will be simple, clear, short and precise. This is how it should be.
This is about not realizing that others do not know what I know. Sounds absurd, but is reality.
And this is also about being both precise and simple, although this sounds like a contradiction.
But first of all this is about lack of communication, or missing willingness to share knowledge. Autism, and people that want even more autists to do software development.
Wordlessness manifests itself in missing // comments and /** documentation */. In the moment when we write source code we are not aware that the things we implement might not be understood any more later. In reality not even their specification will survive the time passing.
And we do not believe that anybody else will have to read and use this source code. A fundamental mistake, but even experienced programmers work that way.
The only way to avoid this is to stick to common sense. Talk to common sense all the time by commenting your code, and making good class-, method- and field-names in a common sense. In comments, do not tell what is obvious by the code itself, tell why you do this or that. Talk about the business logic, not the technical logic.
Make long names, do not use abbreviations and acronyms. Take yourself time to think about significant terms. We would like to read your source code fluently like a book.
Always ask yourself: "Could I understand this source code also a year ahead?". Source code is communication, not compiler directives. Write code for humans, not machines.
We do too much. Outcome are many things that are in the way during maintenance.
Best example are all those public setters and getters that nobody needs nor understands. They expose the state of the object and make it vulnerable, and, once existing, it is risky to remove them. They might be used by some dynamically linked plug-in ...
When we created some cool class and it really works, we want to give it the final touch. Then we add and add and add, so that in the end you also can cook coffee with that class - will anybody want to use that :-?
Who told us to implement all those features? Do we get it paid? Why don't we spend some time by documenting the really needed code that we implemented and tested successfully?
Don't do it when nobody asked for it. Stick to the Agile YAGNI principle: You ain't gonna need it! This will make life much easier for all.
ɔ⃝ Fritz Ritzberger, 2015-09-09