Detailed Notes
What is readable code?
Readable code is simply code that communicates its intent to the reader. It means that when you pull up some code or any type of software, (be it HTML, Java, C, .Net, whatever) that anyone can look at the code and you understand what the code is doing.
Benefits of using readable code
Easier for us to understand what the code is doing. The intent is for any developer to come in, open the code, look at the code and understand what’s going on. Clean and easy to read it make it easier to understand how the code works. When code is written cleanly, it beings to self-document the requirements. If done right anyone can come behind the coder, and easily make a code modification or fix a problem. Makes it easier for us to write testable code, like unit testing. Because if the code is written cleanly then the functionality of our functions, methods, etc… are easier to understand. Such that a tester should be able to identify how the code works, making it easier to test them. Additionally, some other benefits are taking existing documentation such as software documentation and requirement documentation, and taking pieces of this documentation and putting it in the code where it belongs. So, we know that this code goes with this functionality or this requirement.
What happens when we don’t write readable code?
Hard to understand. Complex code can be hard to read. Hard for other developers to follow the developer’s intent because it is not clear. No idea or understanding of how the code works. Typically, when we don’t write readable code, you’ll hear developers say, oh, the code’s unmaintainable it’s spaghetti code. We don’t know what’s going on. Those are signs that your code is not readable. It was not written well. It’s also very hard to make code modifications or fix a problem because the code is unreadable or unmanageable. You don’t know what’s going on or where to begin. Simply put, if you don’t know what’s going on with the code and you can’t read it, you can get stuck.
The same thing applies to testing. If the code is unreadable, you don’t know where to test it. You don’t know how to test or where to test a feature in the software.
There are essentially four ways you can write readable code, but really there are five.
Documentation
Begin with some clear type of documentation. These can be either software requirements, specification documents, some type of test plan, or some other type of business requirements. Essentially, you want some type of documentation around the software that you are going to be writing or changing. So, documentation is really key for writing well-documented readable code.
Coding Standards
Coding standards define how we are going to write our code. Such as, what are the different requirements based on things like our language, environment, architecture, or other significant coding considerations that we should follow. Especially, when we bring in a new developer, making it easier for the new developer to jump in knowing how to write the code, and what to expect when they’re looking at the code. Because everyone is following the same template as they’re writing their code.
Style Guides
Style guides are the way you should organize your code, name variables, name methods, and define classes. Anything that pertains to your language’s basic coding standards, basic style guides, and file naming conventions. For example, in Java, there are specific industry standards around how you name your classes, the way you name your methods or your functions, or the way you name your CSS files.
Code reviews
Code reviews, help in a couple of different ways. One, it helps maintain readability because if someone else reviews it and they can’t understand it, or they can’t read it or they can’t follow it, then it probably needs to go back and be refactored and cleaned up so that it can be understandable.
This also helps flush out any potential logical problems or potential bugs that could be introduced into an application. Something that maybe the tester or the developer forgot to test, or they didn’t think about a particular edge case. These are things that you can look at with or catch what code reviews and code reviews are also a good place to help make ensure that you’re following those coding standards and style guides.
Practice
Finally, we have practice. Unfortunately, this is not something that can be easily done overnight. It takes a lot of time and a lot of practice to get good at writing readable code. Typically, a lot of students come out of college following the examples and derivatives that they were taught in school. They will have one mindset of what coding standards or coding styles are based on whoever taught them.
Transcript Text
thank you [Music] welcome everyone today we are going to be talking about writing readable code so primarily today's discussion is going to be about making our code readable you know what is readable code why do we need it what are some of the benefits of it and essentially how do we write it so we're going to focus primarily on these two four topics today but we're going to be covering it from multiple different angles so primarily we're going to be looking at what is readable code and how do we write it so let's begin with what readable code is so readable code is simply code that literally communicates its intent to the reader so basically it means that when you pull some code or any type of software or be it HTML Java C uh dot net whatever uh that you look at the code and you understand what the code is doing um you know what is the functionality of the code so what are some of the benefits to using readable code you know why do we want to focus on readable code well one it makes it easier for us to understand what the code is so any developer can come in open up the code and look at the code and understand what's going on uh it's very clean easy to read it we can understand how the code works so if the code is written cleanly it's documented well uh I'll be able like for instance someone could come behind you they could easily make a code modification they could fix a problem that's been reported by a customer or they can understand how quickly it is or where to add a new feature or functionality to an application and interestingly enough having readable code also makes it easier for us to write testable code like unit testing j in it PHP whatever because if the code is written cleanly if we have defined our functions methods whatever in a clean way we should be able to identify how to test them it makes it very easy for us to work through this uh some of the other benefits of uh writing readable code is it also takes those like software documentations requirement documentations and we can then take that piece of uh documentation and actually put it in the code where it belongs so we know that this code goes with this functionality or this requirement alternatively if we don't write readable code it's hard to understand uh it's very hard to read it's not very understandable by other developers it's very hard to understand how the code Works typically when we don't write readable code you'll hear developers say oh the code's unmaintainable it's spaghetti code we don't know what's going on those are signs that your code is not readable it was not written well it's also very hard to make code modifications fix a problem because the code is unreadable it's unmanageable you don't know what's going on you don't know where to begin and you also don't know where to add new features because if you don't know what's going on with the code and you can't read it you're kind of stuck you don't know what's going on and then the same thing applies to testing if the code is unreadable you don't know where to test you don't know how to test you don't know where to test different features in the software so how do we write readable count well there's essentially four ways you can write readable code but really I've written five here because it all begins with documentation you have to have some clear type of documentation it's either requirement specification document uh some type of test plan some type of uh business requirements you have to have some documentation around the software that you're going to be writing or that you're going to be updating so documentation is a real key feature here however so many companies and so many organizations skip this step for very small module pieces of requirements in smaller tickets they give you smaller chunks and we don't have that large document giving us a big overview of how our software works so documentation is key the other thing for documentation to think about is you're actually writing a message to your future self with this documentation or a future developer so documentation is basically going to be telling the next person or a reminder to yourself in the future as to what this code is for what are we trying to do with this piece of software the other thing with documentation that is interestingly enough is if you write clear concise documentation about how an application works the different requirements this also can become a good marketing strategy for your sales department to go out and actually sell the application to actually explain it to customers when they're presenting it or doing demos on the software this is also a good area a good piece of uh documentation or a good document to have to basically flush out a lot of the problems that your application could potentially have or bugs or features that were missed in the initial design process so that's where we start is with documentation now this documentation can then be broken down and moved into the code in different places but before we get to that let's talk about the next step so the next feature or the next piece that you need to write readable code is coding standards these basically Define how it is that we are going to write our code what are the different requirements we need based on our language based on our environment based on our architecture that we should follow so that every time we bring in a new developer they are going to know how to write the code what to expect when they're looking at the code and everyone is basically following the same template as they're writing their code if you don't follow a coding standard basically anyone that comes into the organization or anyone that touches your code is potentially following their own rules their own guidelines and it can be a hot mess uh the code could look very different from one class to another from one function to another function uh and really having standards really structure your code and makes it clean makes it readable and everyone can understand what's going on which kind of leads into the style guides so style guides are the way you should organize your code the way you should name your variables the way you should name your methods classes uh all your languages have basic coding standards and basic style guides these are going to be ways that you name your application files like in Java you name your classes the way you name your methods or your functions the way you name your CSS files uh what type of you know do you use CSS files versus inline Styles so there's different ways of coding and different styles for different languages so creating a style guide or following a style guide also helps improve the overall structure of readable code foreign now I've added this fourth one here and this one can kind of be debatable but another way to help your code be readable is to implement the practice of code reviews regardless if it's a SQL script if it's a Javascript file uh javafile.net regardless of the language or what it is any time you write or make a change to an application it makes sense to do a code review code reviews help in a couple of different ways one it helps maintain readability because if someone else reviews it and they can't understand it or they can't read it or they can't follow it then it probably needs to go back and be refactored and cleaned up so that it can be understandable two this helps flush out any potential logical problems or potential bugs that could be introduced into an application something that maybe the tester forgot or the developer forgot to test uh they didn't think about a particular Edge case uh these are things that you can look at with or catch within code reviews and code reviews are also a good place to help uh make ensure that you're following those coding standards and style guts and then lastly practice this is not something that can be easily done overnight it takes a lot of time and a lot of practice to really get good at writing readable code um typically a lot of students coming out of college follow basically the examples and derivatives that they were taught in school they will have one mindset of their coding standards or Styles based on whoever bought them so say you bring five students into one organization from different colleges every single one may have their own styling technique so in order for everyone to get on the same page they need to start learning the coding standards they need to learn the style guides and the only way to really learn this and implement this is to practice to do it then to follow up with code reviews and then make sure that the code reviews that the code meets with the style guides the coding standards and backup to the documentation so it's kind of a top-down approach or bottom-up approach depending upon the direction that you're coming at this so that's it for the slides let's actually jump out today and walk through a code example uh it's a real simple example but it really drives home what readable code is and how to make it work all right so first and foremost I'm using Java but you can use any language PHP Java javascript.net whatever these principles I'll be talking about today pretty much apply to any language uh so it's kind of language agnostic so what I have here is I have this uh project example I created called documentation example now this project in Java has to start lowercase this is a standard naming convention in Java this is a basic Java project with a basic structure so the first thing I did was I just created a class called example one now in Java this isn't really the best practice there's some additional features or some additional coding standards that you should really Implement and that's things like packages where you do com dot the reverse URL of your site now C sharp kind of follows the same practices PHP JavaScript those can be slightly different as well but really depending upon the language you're going to have some actual structure that goes around your application and that kind of gets more into the coding Styles and those foreign so that gets more into those coding Styles and those style guides that we were talking about but I'm not going to focus so much on that today but I'm going to walk through some ideas on how to implement that physically in the code So today we're going to focus just on the code itself so I have this Java class here called example one it's in the package document example and it looks like this we have some methods looks like we have uh four methods here we have some main method which will be where the application in Java starts we have some code in here but really it's not clean really just by looking at this we don't know how this works so if we actually just come up here and try to run this uh we get example uh we get a result of 2.0 well that really doesn't tell us anything so let me actually just run it as a straight Java exam application uh sorry so let me run it at configuration so let me just run this as is no arguments so if we just try to run this program it fails it says Hey exception and thread main Java rate index out of bounds index 0 out of bounds well if you are not a Java developer you're going to be like what the hell does this mean you know what's this exception if you are a Java developer this should actually have been handled uh so this is a bug that potentially we need to fix so to start with we need to then kind of reverse engineer this code or walk through the code and try to understand what's going on well the first thing we look at though is the code is gobblegoop it's a big mess and if you're dealing with JavaScript there's a lot of times where you have to minimize your JavaScript so all your javascript's on one line so it's very hard to read so you essentially need to drop your code into some type of IDE or form formatter and actually let some tool either apply a code style for you or you can apply your own coding format or coding style as you want since we're using Eclipse we can kind of cheat and jump into the default uh parameters for whatever eclipse is set up with so here if I do control shift f or command shift F it's going to reformat our code with all the correct tabs all the correct spaces uh the correct line breaks so that we can actually read the code so that the code is now in a cleaner format so first we look at this this is not real clean not real readable yes we can kind of see everything on the screen but we don't know what's going on it's a hot mess so we first format it there we go all right let me save those changes so the first thing we did was we formatted so now we can see okay we have three methods method one two three and four we have our static main method for Java which runs the application and that's all we have for methods now since I'm using Eclipse I can also open up the Explorer here and this gives me a nice outline view of the program so we see okay we've got Main and we've got four methods here that take two parameters each a float and they return a float value so if we look at it a little bit more we see okay method one looks like we're adding two float values together returning the sum method two or we receive two values we're subtracting okay so we got a minus don't really know why it's just called method two method three we're dividing two float values method four or multiplying so that's what those methods are so right off the bat we can see that okay this makes no sense I really don't understand what's going on but I have to go in to determine what these methods are doing foreign
Transcript Segments
thank you
[Music]
welcome everyone today we are going to
be talking about writing readable code
so primarily today's discussion is going
to be about
making our code readable you know what
is readable code why do we need it what
are some of the benefits of it and
essentially how do we write it so we're
going to focus primarily on these two
four topics today but we're going to be
covering it from multiple different
angles so primarily we're going to be
looking at what is readable code and how
do we write it
so let's begin with what readable code
is so readable code is simply code that
literally communicates its intent to the
reader so basically it means that when
you pull some code or any type of
software or be it HTML Java C
uh
dot net whatever uh that you look at the
code and you understand what the code is
doing
um you know what is the functionality of
the code
so what are some of the benefits to
using readable code you know why do we
want to focus on readable code well one
it makes it easier for us to understand
what the code is so any developer can
come in open up the code and look at the
code and understand what's going on
uh it's very clean easy to read
it we can understand how the code works
so if the code is written cleanly it's
documented well uh I'll be able like for
instance someone could come behind you
they could easily make a code
modification they could fix a problem
that's been reported by a customer or
they can understand how quickly it is or
where to add a new feature or
functionality to an application
and interestingly enough having readable
code also makes it easier for us to
write testable code like unit testing j
in it PHP whatever because if the code
is written cleanly if we have defined
our functions methods whatever in a
clean way we should be able to identify
how to test them it makes it very easy
for us to work through this
uh some of the other benefits of
uh writing readable code is it also
takes those like software documentations
requirement documentations and we can
then take that piece of uh documentation
and actually put it in the code where it
belongs so we know that this code goes
with this functionality or this
requirement
alternatively if we don't write readable
code it's hard to understand uh it's
very hard to read it's not very
understandable by other developers it's
very hard to understand how the code
Works typically when we don't write
readable code you'll hear developers say
oh the code's unmaintainable it's
spaghetti code we don't know what's
going on those are signs that your code
is not readable it was not written well
it's also very hard to make code
modifications fix a problem because the
code is unreadable it's unmanageable you
don't know what's going on you don't
know where to begin and you also don't
know where to add new features because
if you don't know what's going on with
the code and you can't read it you're
kind of stuck you don't know what's
going on and then the same thing applies
to testing if the code is unreadable you
don't know where to test you don't know
how to test you don't know where to test
different features in the software
so how do we write readable count well
there's essentially
four
ways you can write readable code but
really I've written five here because it
all begins with documentation you have
to have some clear type of documentation
it's either requirement specification
document uh some type of test plan some
type of uh business requirements you
have to have some documentation around
the software that you're going to be
writing or that you're going to be
updating so documentation is a real key
feature here
however so many companies and so many
organizations skip this step for very
small module pieces of requirements in
smaller tickets they give you smaller
chunks and we don't have that large
document giving us a big overview of how
our software works so documentation is
key the other thing for documentation to
think about is you're actually writing a
message to your future self with this
documentation or a future developer so
documentation is basically going to be
telling the next person or a reminder to
yourself in the future as to what this
code is for what are we trying to do
with this piece of software the other
thing with documentation that is
interestingly enough is if you write
clear concise documentation about how an
application works the different
requirements
this also can become a good marketing
strategy for your sales department to go
out and actually sell the application to
actually explain it to customers when
they're presenting it or doing demos on
the software this is also a good area a
good piece of uh documentation or a good
document to have to basically flush out
a lot of the problems that your
application could potentially have or
bugs or features that were missed in the
initial design process
so that's where we start is with
documentation now this documentation can
then be broken down and moved into the
code in different places but before we
get to that let's talk about the next
step so the next
feature or the next piece that you need
to write readable code is coding
standards
these basically Define how it is that we
are going to write our code what are the
different requirements we need based on
our language based on our environment
based on our architecture that we should
follow so that every time we bring in a
new developer they are going to know how
to write the code what to expect when
they're looking at the code and everyone
is basically following the same template
as they're writing their code if you
don't follow a coding standard basically
anyone that comes into the organization
or anyone that touches your code is
potentially following their own rules
their own guidelines and it can be a hot
mess uh
the code could look very different from
one class to another from one function
to another function uh and really having
standards really structure your code and
makes it clean makes it readable and
everyone can understand what's going on
which kind of leads into the style
guides so style guides are the way you
should organize your code the way you
should name your variables the way you
should name your methods classes uh all
your languages have basic coding
standards and basic style guides these
are going to be ways that you name your
application files like in Java you name
your classes the way you name your
methods or your functions the way you
name your CSS files uh what type of you
know do you use CSS files versus inline
Styles so there's different ways of
coding and different styles for
different languages so creating a style
guide or following a style guide also
helps improve the overall structure of
readable code
foreign now I've added this fourth one
here and this one can kind of be
debatable but another way to help your
code be readable is to implement the
practice of code reviews regardless if
it's a SQL script if it's a Javascript
file uh javafile.net regardless of the
language or what it is any time you
write or make a change to an application
it makes sense to do a code review code
reviews help in a couple of different
ways one it helps maintain readability
because if someone else reviews it and
they can't understand it or they can't
read it or they can't follow it then it
probably needs to go back and be
refactored and cleaned up so that it can
be understandable two this helps flush
out any potential logical problems or
potential bugs that could be introduced
into an application something that maybe
the tester forgot or the developer
forgot to test uh they didn't think
about a particular Edge case uh these
are things that you can look at with or
catch within code reviews
and code reviews are also a good place
to help uh make ensure that you're
following those coding standards and
style guts and then lastly practice this
is not something that can be easily done
overnight it takes a lot of time and a
lot of practice to really get good at
writing readable code
um
typically a lot of students coming out
of college follow basically the examples
and derivatives that they were taught in
school they will have one mindset of
their coding standards or Styles based
on whoever bought them so
say you bring five students into one
organization from different colleges
every single one may have their own
styling technique so in order for
everyone to get on the same page they
need to start learning the coding
standards they need to learn the style
guides and the only way to really learn
this and implement this is to practice
to do it then to follow up with code
reviews and then make sure that the code
reviews that the code meets with the
style guides the coding standards and
backup to the documentation so it's kind
of a top-down approach or bottom-up
approach depending upon the direction
that you're coming at this
so that's it for the slides let's
actually jump out today and walk through
a code example uh it's a real simple
example but it really
drives home what readable code is and
how to make it work
all right so first and foremost I'm
using Java but you can use any language
PHP Java
javascript.net whatever
these principles I'll be talking about
today pretty much apply to any language
uh so it's kind of language agnostic
so what I have here is I have this uh
project example I created called
documentation example now this project
in Java has to start lowercase this is a
standard naming convention in Java
this is a basic Java project with a
basic structure
so the first thing I did was I just
created a class called example one now
in Java this isn't really the best
practice there's some additional
features or some additional coding
standards that you should really
Implement and that's things like
packages where you do com dot the
reverse URL of your site now C sharp
kind of follows the same practices PHP
JavaScript those can be slightly
different as well but really depending
upon the language you're going to have
some actual structure that goes around
your application and that kind of gets
more into the coding Styles and those
foreign
so that gets more into those coding
Styles and those style guides that we
were talking about but I'm not going to
focus so much on that today but I'm
going to walk through some ideas on how
to implement that physically in the code
So today we're going to focus just on
the code itself
so I have this
Java class here called example one
it's in the package document example and
it looks like this we have some
methods looks like we have uh four
methods here we have some main method
which will be where the application in
Java starts we have some code in here
but really it's not clean really just by
looking at this we don't know how this
works so if we actually just come up
here and try to run this
uh we get example uh we get a result of
2.0 well that really doesn't tell us
anything so let me actually just run it
as a straight Java exam application uh
sorry
so let me run it at configuration
so let me just run this as is no
arguments so if we just try to run this
program it fails it says Hey exception
and thread main Java rate index out of
bounds index 0 out of bounds well if you
are not a Java developer you're going to
be like what the hell does this mean you
know what's this exception
if you are a Java developer this should
actually have been handled uh so this is
a bug that potentially we need to fix
so to start with we need to then kind of
reverse engineer this code or walk
through the code and try to understand
what's going on well the first thing we
look at though is the code is gobblegoop
it's a big mess and if you're dealing
with JavaScript there's a lot of times
where you have to minimize your
JavaScript so all your javascript's on
one line so it's very hard to read so
you essentially need to drop your code
into some type of IDE or form formatter
and actually let some tool either apply
a code style for you or you can apply
your own coding format or coding style
as you want since we're using Eclipse we
can kind of cheat and jump into the
default uh parameters for whatever
eclipse is set up with so here if I do
control shift f
or command shift F it's going to
reformat our code with all the correct
tabs all the correct spaces uh the
correct line breaks so that we can
actually read the code so that the code
is now in a cleaner format so
first we look at this this is not real
clean not real readable yes we can kind
of see everything on the screen but we
don't know what's going on it's a hot
mess so we first format it
there we go all right let me save those
changes
so the first thing we did was we
formatted so now we can see okay we have
three methods method one two three and
four we have our static main method for
Java which runs the application and
that's all we have for methods now since
I'm using Eclipse I can also open up the
Explorer here and this gives me a nice
outline view of the program so we see
okay we've got Main and we've got four
methods here that take two parameters
each a float and they return a float
value so if we look at it a little bit
more we see okay method one looks like
we're adding two float values together
returning the sum method two or we
receive two values we're subtracting
okay so we got a minus
don't really know why it's just called
method two method three we're dividing
two float values method four or
multiplying
so that's what those methods are so
right off the bat we can see that okay
this makes no sense I really don't
understand what's going on but I have to
go in to determine what these methods
are doing
foreign