All common programming languages have features that help you to organize and structure your code. A prominent example are methods and functions. Still, these features are often not used to the extent that they should be.
For example, it is good practice to keep your methods short and comprehensible with a single clear functionality for each method. I won’t argue whether 3, 10, or 20 lines is the perferct size of a method, but 100 lines and more is definitely not. Nevertheless such long methods frequently occur in most systems.
The interesting observation is that the corresponding developers are almost always aware of the lack of comprehensibility of such long methods. But instead of splitting it into multiple smaller methods, the common solution is to use comments to subdivide the long method into its logical parts. So we are talking about comments inside of methods that look like the following:
public void longMethod() {
//-------------------------------------------------------------------
// Read the input ---------------------------------------------------
//-------------------------------------------------------------------
Many lines of code...
//-------------------------------------------------------------------
// Verify the input -------------------------------------------------
//-------------------------------------------------------------------
Many lines of code...
//-------------------------------------------------------------------
// Store the input --------------------------------------------------
//-------------------------------------------------------------------
Many lines of code...
} // end of longMethodWhat a missed opportunity to really improve the code quality!
In most cases it is more than simple to put each logical part in its own method and gain all the benefits of short methods. Note that this applies to all other block-like constructs as well. Do not underestimate the advantages of smaller syntactic units compared to the artifical structuring using comments.
A side effect we often observe is that the closing brace of long blocks is enriched with a comment to indicate which block is actually closed. This is highly susceptible to changes and very likely to become inconsistent soon. After all it’s just a poor workaround for the true problem: Your blocks are too long!