Why Your Code Is So Hard to Understand – via CodeProject
Posted by jpluimers on 2015/09/29
Below are the captions, read the full article as it is very well written.
Why your code is hard to understand
- Problem #1, Overly Complex Mental Models
- Problem #2, Poor Translation of Semantic Models into Code
- Class Structure and Names
- Variable, Parameter and Method Names
- Single Responsibility Principle (SRP)
- Appropriate Comments
- Problem #3, Not Enough Chunking
- Problem #4, Obscured Usage
- Problem #5, No Clear Path Between the Different Models
- Problem #6, Inventing Algorithms
–jeroen
via: Why Your Code Is So Hard to Understand – CodeProject.
The Wiert Corner - irregular stream of stuff 
JustAlurker said
I don’t like this style of directly addressing people with “you” and blaming. It’s invasive. Often also while there is valid criticism ideology and personal taste is pushed down the throat of others at the same time.
I dislike those opinionated posts. Let’s get back to facts and objective views.
jpluimers said
Oh gosh, a lurker is offended.
Eric said
This article is a bit of a tautology, all the points are arguably just different ways of rehashing “if you do not understand it clearly, you cannot code it clearly”, which while true enough, does not address the root of the problem in any way :)
jpluimers said
So what do you think the root of the problem is?
Alexandre Machado said
“Overly Complex Mental Models”… hum… yes you are correct. In general it comes hidden in the “I want to win the most flexible class of the world contest” syndrome. Nowadays, when your requisite tells you that you should create a text file and write a line to it, some developers create 5 classes, 20 interfaces, 25 different files, and the final code can not only write to a text file, but also creates XML and JSON data to respond to a rest client, generates PDF and HTML reports, and also sends an email to your boss when everything is ready.
Besides that: the “I want to win the working program with less lines of code contest” syndrome, is also another problem. When we talk about Delphi it is really scaring that lots of “experts” out there ask for things to make their code shorter (not faster, clearer, less error prone). Some just want to write less code to do the VERY SAME THING that they have been doing for years…