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] so that's not really clean that's not real easy to follow and that's going to make testing a pain in the butt however it gets worse so once we get into our main we then have to instantiate our class so that we can actually run it and example one doesn't really tell us what this program does example one is just an example example of what so that's very unclear we then see that we have we're creating two method variables for float and we are doing some type of parsing float and we're taking the arguments that are coming into the application so this right here tells me that oh so apparently I'm supposed to be getting some arguments but there's no documentation telling me what these arguments are or what this application is supposed to be getting so very unclear so really I don't know what this is supposed to do yet uh and then the second one we're parsing a sec uh so this one here says okay we're going to parse the first parameter that's passed in and this here says we're going to pass the third parameter that's passed in but what the heck is the middle parameter well we have this switch uh case here that looks to do something with the second argument and if we look we see that oh well the second argument apparently is going to be either plus minus divide or uh asterisk and then based on those strings we are going to call the corresponding method based on these uh strings if we don't receive one of these we basically say not a valid function okay kind of figuring out what's going on but it's not easy so we've already spent a couple minutes just trying to understand what's going on but it's not clear so let me start by telling you what this program is so from a high level perspective this program is actually the uh basic structure of a calculator application so if we actually did our due diligence and we have our documentation we can create some Java Docs here that will explain what this class what this program is supposed to be so this is going to be a calculator application and it is going to uh have functions to simulate a calculator to simulate buttons on the calculator all right so right off the bat this now uh makes it a little bit cleaner that we at least now know what this application is we can add things like the author okay who wrote this well I wrote this Michael and we should really add some additional things so in Java with javadocs you can just do the asteroid and you have all these different uh annotations that you can add to your documentation so that when you generate the nice pretty HTML you're going to actually see this uh highlighted or defined so we can do things like API nodes if this is API we have author category is this method deprecated meaning is it about to go away not used anymore we want to hide this we could do since which since is interesting because since we can say okay when was this implemented so we could say this was implemented on August sixth 2022 and we can also add so we have since we can also add version so we could say version zero or version one so when we make changes to this we can update this information and we know what happens so you could actually keep it like this or you can make modifications and say okay modified on eight seven and add the additional information now in the old days uh in old days I mean back in Mainframe days when you were dealing with like Cobalt um again some of the older naming conventions but cold fusion Cobalt um basic things like that back on Old mainframes you had to actually write not just a formatted code but you had to actually write code that was fixed linked in um the style so you didn't have this pretty you had oh it had to be somebody's tabs so many spaces everything had to line up you then had to also include all this information at the top so documentation was Hardcore back in the old days uh because if we didn't we had no idea what was going on all right so we have our high level documentation okay so it's a calculator application we have functions to simulate buttons on the calculator uh I am the author I created it on H6 and we are dealing with version one okay so we now have a class document we have a program document telling us what this is supposed to do the next thing we need to do is we probably need to rename this class or rename this program to actually explain what it is that we are doing what its function really is because example one really doesn't tell us anything so to be a good coder and direct good readable code everything in our code should explain what it is that it's doing so here instead of example one this should be calculator calculate for application now it's telling me okay you've renamed this but in Java standards you have to your class name has to match your file so because we're in Eclipse it's very easy all we have to do is click the rename feature here and it's going to do the work for us so now we have calculator app matches calculator app so now let's kind of walk through the application a little bit so we have this first method here now this first method is actually a method that is going to add two numbers together and here this is actually going to simulate the Plus on a calculator and so method one really should be add float should be left number or we could just say start with this the number one number two XY still work but we want to be a little cleaner we want to make this as clean as possible so you have ADD number one number two now add well it's succinct really still does not explain the functionality of this method we want to be as clear and concise as possible so for good readable code it should be add two numbers together return sum so add two numbers together we could say return sum or add two numbers together return [Music] value so add two numbers together return result okay all right so now we have number one number two so really we can make this a little bit better so left number right number and why I'm being this uh anal about naming it makes sense that when we get down to some of the other methods all right so we we simulate the Plus on the calculator we add two numbers together so really add to numbers result uh returns result so here in Java we could also do uh oops uh Java doc so we can add here and we can add return and we're going to return a float this is the results of adding left number two right number all right so adding two numbers together so now we need to update our return statement so return left number Plus right number now depending upon your coding style uh this is a very simplistic view of coding now you could bloat this up just a little bit which makes it a little more readable but you don't necessarily have to do it it's just depending upon your coding style or the coding uh parameters that are required for coding standards so another way to do this is you could do float some equals left number plus right number and then return sum now if we want to follow the naming convention we can just say results and then we could say return results so just by renaming our code We Now understand exactly what's going on so this first method is supposed to simulate the Plus on the calculator which adds two numbers together and a return is going to be the float result of adding the left number to the right number so now if we actually read the code it almost reads exactly like our comment so we say float add two numbers return result left number float right number we take the float results of left number plus right number and we return the results now if I actually were to remove this comment we get the exact same readability from the code so this is kind of what we call in software development as self-documenting code if you clearly write readable code and follow good coding practices and styles you can pretty much know what's going on in a function or in a piece of code just based on the code itself but it is still helpful to add things like javadocs or class documentation all right so let's do the next one here so I will take this piece here just to cut down on code so this one here we want to simulate the subtraction on a calculator so here we're going to subtract two numbers and we are going to return the float result of subtracting the left number from the right number so this should actually instead being just method two should be sub tract two numbers return result again left number right number now one additional piece of documentation you could add to this method is if people don't understand uh math which there are people out there is if the left number or I'm sorry if the right number is greater than the left number we will get Okay negative or we should get we will get we should get a negative number so this is just a rule a subtraction all right so float results number right so we subtract two numbers return results so let's do the same thing we did before so we'll do float results equals x minus y return results but wait x minus y doesn't exist it needs to be left number right number all right let's read this so subtract two numbers uh we'll receive left number and right number our result is going to be the subtraction of uh left number minus right number so simulate the minus on the calculator subtract two numbers float returns results so subtracting left number from right number okay makes sense so far all right so method three so we now want to simulate the division on a calculator now this is not to be confused what it did on Java we have a div method or a div property which is the remainder of a division not the division itself so here we want to divide two numbers and there is a division rule and our division rule we cannot divide by zero this will return uh this is bad so this returns not a number all right so our float results of dividing left number from right number so again we should make something a little more distinct for our naming so float change this to divide two numbers left and right and we'll return results and let's do method four so now we want to simulate the multiplication foreign and here we're going to multiply two numbers don't need a rule for that and Float result of multiplying left number two right now so we need to change method four to be multiplied two numbers return results foreign X and Y to left and right number and it said divide we will multiply all right so so far so good we understand now that we have a calculator application we're simulating the buttons on a calculator so calculator application is the name of our program we have four methods for adding two numbers dividing two numbers multiplying two numbers and subtracting two numbers and these return results all right last and not least we have our main so this is pretty much just the main app uh Main that's that so this is where what runs our code all right so first things first we need to change or we need to basically tell the end user what parameters this application requires so really we need to make sure that if there are no arguments we need to check for that so main method runs code foreign we actually do need some Java dots so here we have arguments some parameter R and zero is going to be the left number we have argument one and argument two argument one is going to be our calculator button value plus minus divide what our application is going to so our application is going to accept three values simulating two numbers and a math symbol being entered into a calculator for example left number uh right number Etc but for readability let's just do all of it we have left number plus minus slide and multiply so now we know what our main method is supposed to do so we are expecting three values so if we don't get these three values we're going to fail so first thing this program actually needs to do is we need to add an additional condition so we need to say if ours equal args equal null foreign is less than three less than or equal to three no less than three yeah that's right I had my curly braces for readability we can do just about and what we want to see is we want to say our calculator app so in Java this is kind of expected formatting so we can do calculator app we say required or calculator app requires uh left number operation price number [Music]
Transcript Segments
thank you
[Music]
so that's not really clean that's not
real easy to follow and that's going to
make testing a pain in the butt
however it gets worse so once we get
into our main we then have to
instantiate our class so that we can
actually run it and example one doesn't
really tell us what this program does
example one is just an example example
of what so that's very unclear
we then see that we have we're creating
two method variables for float and we
are doing some type of parsing float and
we're taking the arguments that are
coming into the application so this
right here tells me that oh so
apparently I'm supposed to be getting
some arguments but there's no
documentation telling me what these
arguments are or what this application
is supposed to be getting so very
unclear so really I don't know what this
is supposed to do yet
uh and then the second one we're parsing
a sec uh so this one here says okay
we're going to parse the first parameter
that's passed in and this here says
we're going to pass the third parameter
that's passed in but what the heck is
the middle parameter well we have this
switch uh case here that looks to do
something with the second argument and
if we look we see that oh well the
second argument apparently is going to
be either plus minus divide or uh
asterisk and then based on those strings
we are going to call the corresponding
method based on these uh strings if we
don't receive one of these we basically
say not a valid function
okay kind of figuring out what's going
on but it's not easy so we've already
spent a couple minutes just trying to
understand what's going on but it's not
clear
so let me start by telling you what this
program is so from a high level
perspective this program is actually the
uh basic structure of a calculator
application
so if we actually did our due diligence
and we have our documentation we can
create some Java Docs
here that will explain what this class
what this program is supposed to be so
this is going to be a calculator
application
and it is going to uh have functions
to simulate
a calculator
to simulate buttons on the calculator
all right so right off the bat this now
uh makes it a little bit cleaner that we
at least now know what this application
is we can add things like the author
okay who wrote this well I wrote this
Michael and we should really add some
additional things so in Java with
javadocs you can just do the asteroid
and you have all these different uh
annotations that you can add to your
documentation so that when you generate
the nice pretty HTML you're going to
actually see this uh highlighted or
defined so we can do things like API
nodes if this is API we have author
category is this method deprecated
meaning is it about to go away not used
anymore we want to hide this we could do
since which since is interesting because
since we can say okay when was this
implemented so we could say this was
implemented on August
sixth
2022
and we can also add so we have since we
can also add version so we could say
version zero or version one
so when we make changes to this we can
update this information and we know what
happens so you could actually keep it
like this or you can make modifications
and say okay modified
on
eight seven
and add the additional information
now in the old days uh in old days I
mean back in Mainframe days when you
were dealing with like Cobalt
um
again some of the older naming
conventions but
cold fusion Cobalt
um basic things like that back on Old
mainframes you had to actually write not
just a formatted code but you had to
actually write code that was fixed
linked in um
the style so you didn't have this pretty
you had oh it had to be somebody's tabs
so many spaces everything had to line up
you then had to also include all this
information at the top so documentation
was Hardcore back in the old days uh
because if we didn't we had no idea what
was going on
all right so we have our high level
documentation okay so it's a calculator
application we have functions to
simulate buttons on the calculator
uh I am the author I created it on H6
and we are dealing with version one
okay so we now have a class document we
have a program document telling us what
this is supposed to do
the next thing we need to do is we
probably need to rename this class or
rename this program to actually explain
what it is that we are doing what its
function really is because example one
really doesn't tell us anything so to be
a good coder and direct good readable
code
everything in our code should explain
what it is that it's doing so here
instead of example one this should be
calculator
calculate for
application
now it's telling me okay you've renamed
this but in Java standards you have to
your class name has to match your file
so because we're in Eclipse it's very
easy all we have to do is click the
rename feature here and it's going to do
the work for us so now we have
calculator app
matches calculator app
so now let's kind of walk through the
application a little bit so we have this
first method here now this first method
is actually a method that is going to
add
two numbers
together
and here this is actually going to
simulate
the Plus
on a calculator
and so method one really should be add
float should be left number
or we could just say
start with this the number one
number two XY still work but we want to
be a little cleaner we want to make this
as clean as possible so you have ADD
number one number two now
add well it's succinct really still does
not explain the functionality of this
method we want to be as clear and
concise as possible so for good readable
code it should be add
two numbers
together
return
sum
so add two numbers together we could say
return sum or add two numbers together
return
[Music]
value
so add two numbers together
return result okay
all right so now we have number one
number two
so really we can make this a little bit
better so left number
right number
and why I'm being this uh anal about
naming it makes sense that when we get
down to some of the other methods all
right so we we simulate the Plus on the
calculator we add two numbers together
so
really add to numbers result uh returns
result so here in Java we could also do
uh oops uh Java doc
so we can add here and we can add return
and we're going to return a float
this is the results
of adding left number
two right number
all right so adding two numbers together
so now we need to update our return
statement so return
left
number Plus
right number now depending upon your
coding style uh this is a very
simplistic view of coding now you could
bloat this up just a little bit which
makes it a little more readable but you
don't necessarily have to do it it's
just depending upon your coding style or
the coding uh parameters that are
required for coding standards so another
way to do this is you could do float
some
equals
left number plus right number and then
return sum now if we want to follow
the naming convention we can just say
results
and then we could say return results
so just by renaming our code
We Now understand exactly what's going
on so this first method is supposed to
simulate the Plus on the calculator
which adds two numbers together and a
return is going to be the float result
of adding the left number to the right
number
so now if we actually read the code it
almost reads exactly like our comment
so we say float add two numbers return
result
left number float right number
we take the float results of left number
plus right number and we return the
results
now if I actually were to remove this
comment
we get the exact same readability from
the code
so this is kind of what we call in
software development as self-documenting
code if you clearly write readable code
and follow good coding practices and
styles you can pretty much know what's
going on in a function or in a piece of
code just based on the code itself
but it is still helpful to add things
like javadocs or class documentation
all right so let's do the next one here
so I will take this piece here just to
cut down on code
so this one here we want to simulate the
subtraction on a calculator so here
we're going to subtract
two numbers
and we are going to return the float
result of subtracting
the left number from
the right number
so this should actually instead being
just method two should be sub
tract
two numbers
return result
again
left number
right number
now one additional piece of
documentation you could add to this
method is
if people don't understand uh math which
there are people out there is if the
left number
or I'm sorry if the right number
is greater
than
the
left number
we will get
Okay negative
or we should get
we will get we
should get a negative number
so this is just a rule
a subtraction
all right so float results
number right
so we subtract two numbers return
results so let's do the same thing we
did before so we'll do float
results
equals
x minus y
return results
but wait x minus y doesn't exist it
needs to be left number
right number
all right let's read this so subtract
two numbers
uh we'll receive left number and right
number our result is going to be the
subtraction of uh left number minus
right number
so simulate the minus on the calculator
subtract two numbers
float returns results so subtracting
left number from right number
okay
makes sense so far
all right so method three
so we now want to simulate the division
on a calculator now this is not to be
confused
what it did on Java we have a div
method
or a div property which is the remainder
of a division not the division itself
so here we want to divide two numbers
and there is a division rule
and our division rule
we cannot divide by zero
this will return uh this is bad so this
returns
not a number
all right so our float results of
dividing
left number from right number
so again we should make something a
little more distinct
for our naming
so float
change this to divide
two numbers left and right
and we'll return results
and let's do method four so now we want
to simulate the multiplication
foreign
and here we're going to multiply
two numbers
don't need a rule for that
and Float result of multiplying
left number two right now
so we need to change method four to be
multiplied two numbers return results
foreign
X and Y
to left and right number
and it said divide we will multiply
all right so so far so good we
understand now that we have a calculator
application we're simulating the buttons
on a calculator
so calculator application is the name of
our program
we have four methods for adding two
numbers dividing two numbers multiplying
two numbers and subtracting two numbers
and these return results
all right
last and not least we have our main
so this is pretty much just the main app
uh
Main
that's that
so this is where what runs our code
all right so first things first
we need to change
or we need to basically tell the
end user
what parameters this application
requires
so really we need to make sure that if
there are no arguments we need to check
for that so main method runs code
foreign
we actually do need some Java dots so
here we have arguments
some parameter
R and
zero
is going to be the left
number
we have argument one and argument two
argument one is going to be our
calculator
button
value
plus minus
divide
what
our application is going to
so our application
is going to accept
three values
simulating
two numbers
and
a
math symbol
being entered into a calculator
for example
left number
uh
right number
Etc
but for readability let's just do all of
it
we have left number
plus minus
slide
and multiply
so now we know what our main method is
supposed to do so we are expecting three
values so if we don't get these three
values we're going to fail
so first thing this program actually
needs to do is we need to add an
additional condition so we need to say
if
ours
equal args equal null
foreign
is less than three
less than or equal to three no
less than three yeah that's right
I had my curly braces for readability we
can do just about
and what we want to see is we want to
say our calculator app
so in Java this is kind of
expected formatting so we can do
calculator app
we say required
or
calculator app requires
uh
left number
operation
price number
[Music]