- [Instructor] Now that we know
what a coding standard is, let's go through the steps
for creating and enforcing one.
The process for creating a coding standard is iterative,
much like specifying software.
First, determine what coding conventions are available
that fit your project or organization.
Out of what's available,
decide what has the most positive impact
on the quality of your code base and morale.
Some rules help developers
while others may annoy and may be needlessly strict.
Experiment with what's out there to find what works
and what doesn't.
When you've made a choice,
briefly document the justification
of why you've chosen to use or not use a particular rule.
Less is more, so try for a maximum of one sentence.
Once the rules have been defined,
create the configurations for any software you're using.
We're going to be discussing
how to do this later on in the course.
Finally, revisit the rules on a regular basis
to make sure they're logical.
Some may work and others won't
and new ones might be available.
When creating and implementing a coding standard,
there are a few things to keep in mind.
While you may be passionate about it,
be sure to involve the whole team.
Especially when it comes to choosing rules,
share the decision-making.
A coding standards should be built out of consensus.
Through involvement, team members will have shared ownership
and will be happier with the result.
The goal of a coding standard,
especially when there is existing code,
is gradual improvement over time.
Be patient because you can't turn a cruise ship on a dime.
Too much change, too fast causes problems.
There are a few pitfalls
to watch out for when creating a coding standard.
If there are too many rules,
programmers may feel confined and micromanaged.
If the rules are needlessly strict
and are causing false positives,
or are taking too long to satisfy,
relax or remove them.
For example, spell checking comments,
which may be an aggravation for some
may not be an effective use of time.
Finally, avoid overly pedantic rules
such as requiring new lines in ternary expressions.
This is a negative situation
where the focus is on literal accuracy
instead of practical.
I know, this might be ironic
to hear in a course like this.
But I'm trying to stress the practical use cases.
Learn from my mistakes.
So, with all these rules, how can they be enforced?
The best way to enforce a coding standard automatically
is by using a linter.
What's a linter?
A linter is a tool that scans code
to look for suspicious usage, such as syntax errors
and coding convention violations.
A linter performs static analysis,
meaning it does not execute the program itself.
This makes it very fast and unobtrusive.
Linters can be configured with sense of rules,
which look violations of specific coding conventions.
Linters can be useful, but why should you use one?
Well, they're incredibly fast.
Again, because they're just scanning
and tokenizing the code and not actually executing it.
Linters are accurate
and have undergone massive amounts of peer review
and testing.
They're consistent, giving the exact same results each time
on the same piece of code,
which is useful for measuring progress.
A linter is impersonal in that it just reports
what it's told to and doesn't care about your feelings.
It can be better to get criticism
from something that has no emotion,
rather than someone you know.
To make up for that,
linters can automatically fix some of the problems
they find, which is a big time saver.
Finally, linters integrate with most text editors
giving you real-time feedback as you edit your code.
I like knowing about and fixing problems
before I send something off for peer review.
While there are a variety of different linters,
the reported results of a linter analysis
have a similar format.
First, it gives context about the affected location,
specifically the file, line number,
and sometimes the character where the problem begins.
Then it provides the severity or how bad the problem is.
It can be an error which has to be addressed,
or a warning which should be looked into
as it may be causing problems.
Next comes a description,
which is the human readable explanation of the problem.
It's typically a short sentence.
Finally, the machine name of the rule that was triggered
in case you need to do more research
or possibly disable the rule.
Here's an example of linter output.
The first line is the complete path to the file.
On the second line, it starts with the line number
and character of where the problem is.
The severity, which in this case it's an error, comes next.
The description of the problem is included.
Then finally, the name of the rule that was triggered.
Of course, there's always a possibility of a false positive.
Sometimes a rule is too sensitive
or a whole file maybe third-party code and can't be changed.
And therefore should be excluded from the scan.
Fortunately, both individual lines
and entire files can be selectively ignored.
Sometimes all that is needed is a bit of tuning
around the configuration of a rule
to adjust it to your code base.
If the rule is becoming troublesome,
reconsider the use of it
rather than just getting frustrated
or halting linting in general.
If there is a genuine problem,
submit a bug report to the linters maintainers
to let them know of the issue.
Automated scanning is fantastic.
But what about the role of linting with peer reviews?
A linter should be run before a peer review,
not during or after.
A peer review should be about the logic
and intent of your code,
not something that an algorithm can enforce.
Both the reviewer and the developers should have similar
and reasonable expectations around linting.
A good practice that I use
is that new and modified code should pass the linter.
That way, things improve over time
and don't require a massive refactor
that can hide other bugs.
We've been discussing coding conventions
and rules that can be enforced with linters.
What about rules for peer reviewers?
There's a fantastic book
called "The Elements of Programming Style."
First published in 1974,
it's not a book about how to program,
it's about the human factors of programming
and code quality.
Some of the summarized programming style tips include,
write clearly, don't be too clever.
Say what you mean, simply and directly.
Use library functions whenever feasible.
There are dozens of additional tips
which are summarized at the end of the book.
To review, a linter is a tool that scans code
for suspicious or questionable practices.
Linters statically analyze code,
meaning they don't execute.
A linter can be configured with rules
that specify code conventions.
We've been talking about linting and coding standards.
So, how do we go about using them?
Chapter two will cover using linting tools
and compare some approaches.
We've covered programming styles and coding standards.
So, how do we go about testing software?