- [Instructor] The easiest way to improve code quality
and specifically maintainability
is to use a coding standard.
But what's a coding standard?
To answer that, let's step back
and answer a different question.
What is a coding convention?
A coding convention is a set of guidelines
and recommendations for writing programs
in a particular language.
Coding conventions typically consists of three things.
The first is a programming style
which usually deals with the readability of source code.
The second are practices
or ways to build an architect programs.
The third are methods, which are the way to plan
and implement a program, including requirements,
design, specifications and so forth.
With that in mind,
how is a coding convention used?
Well, a coding standard
is a collection of coding conventions.
They have been selected and designed specifically
to produce quality code, including functional requirements
and maintainability.
A coding standard is a formal specification
that a group or organization has adopted for projects.
Both programming practices and methods
are fascinating topics.
With that said, those topics are out of scope of this course
because they're about organization and management.
Instead, I'm going to focus on programming styles
because of their profound impact on code quality.
There are a number of common programming style conventions.
I'll briefly list them
then go into greater detail about each.
The first are around comments
which programmers read and interpreters ignore.
Next is whitespace or unused space around an object.
Different naming conventions for identifiers,
such as variables, functions and methods are included.
The conventions also have ways
to avoid possible human errors, such as unreachable code.
There are a number of other conventions as well
that don't fit any of these other subjects,
such as security, spelling and more.
Let's take a closer look at programming style conventions,
starting with comment conventions.
The most common are the documentation
of methods and functions.
While it's not practical to check the contents,
you can see if the docs exist.
It's possible to validate the signature of the docs,
meaning check of the arguments and the docs
match the arguments in the declaration.
Some conventions even include spelling,
punctuation and grammar.
Before you roll your eyes and scoff,
these types of conventions
are about the culture of the project or the institution
which may expect excellence in all areas
including the code base.
Some basic formatting conventions exist
such as how to handle multi-line comments.
It's typical to prefer the multi-line comments
over multiple sequential single line comments.
Spacing between the comment character
and the start of the actual comment improves readability.
Speaking of spacing, whitespace conventions
are also important.
The debate over spaces versus tabs is a long-standing one.
Regardless of your opinion, you have to choose one
or the other and the quantity,
otherwise the code base will become a formatting mess.
The length of lines of code is also important
for readability.
As an example, 100 characters is a good starting place.
The number of sequential empty lines should be specified.
Since there's no semantic meaning,
it's typically limited to one or two.
The line endings or new line characters
should also be consistent.
There are three formats.
The most common is just the line feed character
for Unix, Linux and Mac.
Another variation is both carriage return
and line feed for windows and dos.
A less common variation is just carriage return on Mac.
Again, consistency here is really important
so file histories aren't wiped out
or text editors get messed up.
Whitespace also matters in statements
including block statements.
For example, this spacing between the parentheses and brace.
Should there be a space or no space?
There's a similar question for control statements as well.
Should there be no space
after a control statement or use a space?
There's no functional difference between the two
but consistency and readability are important.
Another style convention is around the naming of identifiers
and object properties.
Capitalization has no functional impact,
but does have semantic meaning.
For example, data types and constructors
typically use Pascal case
also known as upper Camel case.
Methods typically use lower Camel case.
The length of identifiers can be important
and easily overlooked.
Is N too short of a variable name?
Before you answer, given absolutely no context
do you know what N means?
Turns out I meant it to be the name of a planet.
Conversely, is my dog has a first name
it's major and he's fuzzy too long?
Yeah, it's too long.
Please don't do that.
It's silly and could be considered malicious compliance
which is bad for morale and teams.
Identifier names should be appropriately meaningful.
This is something a linter can't do
but a peer reviewer can.
Similar to length,
what does I mean?
What about foo?
You can even be just completely wrong
and assign puppy to a new orange.
It's valid syntax, but it's unmaintainable code.
There are some logical pitfalls as well
that are possible errors.
They're syntactically legal
meaning it won't cause a hard crash,
but they lead to unreachable code
and other unintended problems.
For example, double semi-colons.
Probably a typo or a copy and paste.
What about checking the type of something
to see if it's stirng not a string.
What about throwing an error
then having something execute after the throw?
These are signs of bugs and can indicate potential problems
so they should be resolved.
To review, coding standards are a formal collection
of coding conventions.
Each convention is a rule about code quality.
The goal of coding standards is to improve maintainability
and the usefulness of the software.
There are a lot of potential code conventions,
so, how do you go about creating
and enforcing a coding standard?