
Writing better Code (extension to Joel's 12 steps to better Code) - gerlacdt
https://gerlacdt.github.io/posts/writing-better-software/
======
goto11
> 23\. Do you focus on the four key metrics?

Sorry, you lost me on this one! All metrics will be gamed to uselessness. I'm
sure Joel already wrote something sarcastic about this 20 years ago.

~~~
Cpoll
The metrics listed are:

> Short lead time

> High deployment frequency

> Short mean time to restore (MTTR)

> Low change fail percentage

Those aren't as easy to game as LoC, which is the usual example for gamed
metrics when people say "a metric that becomes a target stops being a good
metric."

I think that saying is contextual, in any case. If you take it to the logical
extreme you have to make organizational decisions without any information.

------
the_arun
Not sure the question in the original set - Do you have testers? - make sense
in the current generation. May be we could rephrase - Do you have a way to
test critical flows of the application in automated fashion?

------
nwah1
To enforce a common code style, the best solution is to use EditorConfig

------
ncmncm
After quite a few decades' experience with style guides, I have determined
that they are vastly over-valued, and often very actively harmful.

There are three major problems with typical style guides (including yours):

1\. Triviality

They legislate behaviors that are easy to express and police, but don't
actually result in better code. This is a big evil because it distracts from
hard-learned behaviors that do make better code.

Programmer attention is the scarcest resource any of us have. Almost all bugs
trace to a lapse somewhere. Hence, anything that squanders attention actively
generates bugs. Lining up columns generates bugs.

How often have you got review notes that mentioned nothing but style
trivialities? Did the reviewer have attention to spare for things that will
matter?

2\. Obsolescence

Style guides are invariably obsolete on their first day, and only get worse.
Updating a style guide is always contentious, rightly recognized as a waste of
senior engineers' time, yet not to be trusted to their juniors. So, the guide
is for a language as it might have been used (somewhere) five, ten, 20 years
ago. Current best practices are not mentioned at all.

Worse, if it ever is updated, none of the existing code conforms anymore.
Nobody is so foolish as to try to bring all old code up to new requirements.
Automated updates can only address trivial changes. So, you have an official
style that is either badly out of date, or at best doesn't match the code you
have.

3\. More obsolescence

Besides the style guide's own obsolescence, it legislates code constructs that
are obsolete. "This is why we can't have nice things." Each bit of new code
that conforms to the old guide for bad or trivial reasons amounts to more tech
debt.

Ultimately, there is no substitute for competence. Good engineers will not
write hard-to-read code. Somebody who does will, despite the best guide. Your
only hope is to demand competence.

Instead

What can we do, then, to avoid chaos?

First, instead of mandating trivialities, identify principles and goals. Refer
to concrete benefits to code quality. Good principles will address very
different topics than your style guide did. Structs should have not too many
members, functions limited size, names be (only) long enough to be readily
distinguished from others, whitespace draw attention to places that need it,
not wasted on highlighting nothings. The principles are based on psychology
and the limits of attention, not typography.

Consistency is good in small amounts, and harmful in the large. When there are
old ways and a new way of doing things, people reading code can easily adjust
to each where it appears, recognizing that old code is that way because it is
old. Changing habits become a useful marker of code origin.

The useful range for consistency is not a project, or folder, or file. It is
at most 20 lines.

~~~
goto11
IMHO code guidelines are there to _avoid_ wasting time on trivialities. Why
would something which is already settled by the guidelines even crop up code
reviews, except for the first few commits from a junior developer?

Lots of style choices are more or less arbitrary. PascalCase or camelCase? Big
endiand or little endian? Comments and identifiers in english or french? You
cant just "demand competence" because neither is clearly superior. But
consistency is clearly superior to everyone doing it their own way. So you
make a decision, write it down in a guide, and the question will not take up
any more time and attention.

But yeah, a guideline which legislates obsolete code constructs is obviously
bad. Clearly something is deeply wrong in the culture of the team if the
guideline is 20 years out of data and no one care about updating it - while at
the same wastes a lot of resources on pointing out the issues in code reviews!
But that problem is not with guidelines per se. Using an obsolete compiler
will probably also give you problems.

