16 \ November 2018 \ http://www.phparch.com
How to Knock Down Any Project in Ten Steps
- Low Code Quality and
Lack of Standards
As Uncle Bob wrote^1 , “Indeed, the
ratio of time spent reading versus writ-
ing is well over 10 to 1.” The rest of the
time we try to understand the existing
code and match it with your solution.
If the existing code is of poor quality
and incomprehensible, we will spend
more time trying to understanding it.
Experience suggests that most likely, as
a developer, you will add your code, but
you will not correct what already exists,
update documentation, add tests, or fix
incorrect comments. If you read the
code and don’t understand it, it’s not
written simply enough.
There are many things that make up
the overall quality of the code:- legibility,
- naming things in the code,
- magical numbers,
- god classes,
- not using appropriate data struc-
tures, - duplication of code,
- no global configuration,
- useless comments,
- no tests, and
- no documentation.
Poor code quality and shortcuts lead
to the generation of technical debt.
In the long term, it will slow down
the development of the application
and hinder its maintenance. There-
fore, choosing to use low-quality code
should always be conscious, and it
is worthwhile to reserve time in the
future to improve the quality if we can’t
do it right away.
1 wrote: https://phpa.me/martin-ratio-time
- No Tests
Testing is not responsible for the
bugs inserted into software any
more than the sun is responsible for
creating dust in the air.- Dorothy Graham
Lack of automated tests is a very
common problem. I often hear devel-
opers state they don’t have time to write
tests. Nothing is more wrong! Tests
should be written precisely because we
do not have time. It is a waste of our
time to test the same things before each
deployment. It’s a waste of our time,
after each fix, to confirm the old errors
haven’t returned. It’s a waste of our time
to do manual tests over and over again.
Once spent, the time invested in writ-
ing tests will pay for itself many times
over.
It is no longer even about using Test-
Driven Development (TDD) because in
TDD tests are a side effect. The point is
that by automating tests, you can give
yourself more time for more important
things than fixing the same mistakes.
It is also about documenting use cases
and facilitating refactoring in the future.
However, the mere fact of having
tests is not enough. You have to look at
the quality of these tests: do they test
something beyond the happy path? Do
they test edge cases? Do we have unit
tests, acceptance tests, integration tests?
Are we ready for random events, such as
lack or interruption of communication
with the database, the queue system,
sudden hard drive failure while reading
the file? The more critical system we
are working on, the more emphasis is
placed on the correct functioning, and
more tests are worth having.- Lack of Documentation
Incorrect documentation is often
worse than no documentation.- Bertrand Meyer
In the subject of documentation, the
most common case is simply a lack of
documentation. However, this is not
the worst case possible. Worse, if there
is documentation, but it is outdated and
thus misleading. We lose valuable time,
and although we might gain knowl-
edge about how the element worked
in the past, this is in no way applicable
to the present. Documentation errors
are on par with code errors, and any
undocumented code is legacy code.
During code review we should treat not
updating the docs as a potential breach
of standards—this approach makes it
easier to minimize the risk of outdated
documentation.
Example: a Proof-of-Concept (POC)
is created to check if the library can be
used in a new microservice. During
code review, questions about tests and
documentation were mostly ignored,
because “it’s just the POC.” Two weeks
later, the POC—without tests and docu-
mentation—is put into production. The
author is delegated to some other proj-
ect, and the maintenance is to be taken
care of by the rest of the team. To put it
mildly, the situation in which the team
was placed and the code author’s behav-
ior were far from perfect.
Writing documentation may not be
the most exciting activity, but its part of
any well-done job. Its value pays off in
the future when we need to come back
to the project.
Documentation, like any other code,
should be subject to the code review
process. Even if it is supposed to look
different formally, ask a colleague to
review what you have written because it
should be checked for comprehension.
It’s even better to ask someone who
doesn’t work on this project on a daily
basis to ensure you don’t use jargon or a
specific vocabulary that could be better
explained.