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] and then if we wanted to we could add some additional syntax to make it easier we could say this there's a couple different ways you could do this readability wise it's easier to do sys out on multiple lines sometimes it's easier to do line breaks again this just depends on your coding standards calculator application of number operation right number an if float number for decimal value operation does it needs math operator a value of Plus minus divide or multiply and right number an eight float number or decimal so just starting there I have one other thing I have to do so if we were to run this instead of getting index out of bounds we would actually get this message written now now in order for me to test that I do need to update one thing here so we did rename the application from example one so we need to change this to be our calculator [Music] I need to name it the name of our class so calculator location you know calculator application we need to make our variable a little more uh readable uh ex makes no sense so we know we want to reference the methods in calculator application so really we should just call it calculator application uh calculate or application so we know the method or we know the class that we're calling we know argument zero and argument two are going to be left and right numbers so we'll say 11 number right number uh argument one so one of the things we can do is we can also do this so we can pick in the values we can say spring operator to be clear so we'll take operator and we will set it equal to args one so now as we do our case statement we do our switch on operator so if operator is plus minus divide or multiplication we know what methods we need to call so then we're going to call calculator application and instead of method one we're going to do add two numbers together and instead of art zero and one we will do the left number and right now now the beauty of this is if you've named your application and your methods clearly especially your parameters if I were to just Say Hey I want to do uh this is where the code completion comes in handy so I can take calculator application add to numbers and it will automatically pull in the syntax from our methods so we have the variable name left number and right number so if we actually name things the same name our our local local variables the same everything translates together everything is readable it flows so we have this so we have calculate application again dot this is going to be a subtraction calculator method Dot slide and then calculator method or calculator application sorry multiply and then last but not least so not a valid operator so let me maximize this for readability so we'll come back through here so we have our document description for the application it's going to be a calculator application it's going to have functions to simulate buttons on the calculator right application was started written by me uh started today version one our application name our method names are very clear so we simulate Plus on a calculator add two methods return the results our description add two numbers together so we get two numbers we add them together and we return the results of those two numbers same for mult uh for minus divide and multiply now we'll get to the rules in a minute but just follow me so far So based on how we've renamed this everything is readable so even if we were to delete our javadocs the code is pretty straightforward it's pretty readable pretty understandable so if you come down here to the main method now so even if we didn't have the javadoc here just because we added this method here or this is out this is essentially that document so if I try to run this as is so now we get our application is going to accept three values simulate two numbers and a math symbol being entered into a calculator command calculate application left number operator right number and it tells you what needs to be passed in because we didn't it through the exception now we can handle that exception by simply returning adding a return here return system exit zero actually just do system.exit zero system.exit zero exits the application cleanly so now if we run this we get our message and we don't get the exception but um what we need to say is um I'm able to run command syntax and you can name this however you want but just um you want to make it as descriptive as as possible so applications kind of takes up three values simulate two numbers unable to run commands syntax should be uh calculated application left operator right number and then here are our values all right so we have our method we can run it so if we actually get Pat get the right values we should calculate the operations all right so to do that we need to go into our run configuration and set up some arguments so let's add one plus one and run we get 2.0 if we run again one minus one we get zero if we run again 1 divided by one we get one and so on so as you can see we can now run the application now to thoroughly test the application we should add some unit testing or other test classes essentially that do what simulate what I just did um but other than that this is pretty much how we self-document our code so now if I look at here I can look at the outline so I have my calculator application I have my main I have add two numbers divide two numbers multiply subtract uh if I were to uh way I can build the Java Docs there we are generate Java Docs destination yep Ducks finish yes to all so it just generated the Java docs so if I come out here here's my documentation so if I open with web browser so we have our clean Java docs or whatever tool you use to generate docs we have our package name we have our project so we have our class calculator application brief description very clean easy to understand go into the calculator application so we calculate applications uh have function to simulate buttons on the calculator since version author here's our Constructors we have our methods so main our application is going to accept three values methods inherent from class we have our Constructor and we have our methods oh that's what I samples when you generate Java docs you need to include there we go there we go so when you generate your javadocs you can generate the ones for package private static public because I did not actually declare these as public they were a class or package level so when I regenerate it now we get our additional method so there's add two numbers divide two numbers multiply and then here's our documentation so to write readable code you can as you can see basically it just means writing code in plain English uh or whatever language you're in you basically take the what the application or the program is supposed to do and break it down into its individual parts and then document it accordingly or write your methods uh variable names or even the calculations in such a way that if you just read the code you understand what that particular piece of code is doing otherwise if you start out with the initial example I had it looks like spaghetti code very hard to follow not real easy to test and as you saw we really didn't even know what the application was doing just by trying to run it foreign so let's go back over to the slides so does anyone have any questions is this how a developers when they bring in a developer and they tell him that hey please clean up this code is this what they'll be doing like pretty much going through each and every method to see how can they make it simpler maybe for the next developer or somebody uh depending upon what they're actually asking them to do yes um it could be twofold one cleanup the code could mean uh that you have very complex methods uh where the functionality of the method uh or the program itself could be doing multiple things so for instance uh say instead of doing all the individual methods for uh add divide multiply subtract maybe I had a method that just said um calculate numbers and you passed in uh all three variables uh float string float but you really didn't know what functionality really happened inside that method but inside that method you basically had all of this info uh all this complex calculation so you had uh oh okay so if it's left number do this if it's or plus do this minus do this so like this could have like all this code could have been in one method so instead of the system.outs where I call the method all that functionality could be in one method or program and a lot of times when you're asked to clean up code or refactor code what you're doing is you're taking all these complex uh basically pieces of code which are actually smaller pieces of code and you break them down into their smaller uh components like multiply divide [Music]
Transcript Segments
thank you
[Music]
and then if we wanted to we could add
some additional syntax
to make it easier
we could say this
there's a couple different ways you
could do this readability wise it's
easier to do sys out on multiple lines
sometimes it's easier to do line breaks
again this just depends on your coding
standards
calculator application
of number
operation
right number
an if float number
for decimal value
operation
does it needs math
operator
a value
of Plus
minus divide
or multiply
and right number
an eight float number or decimal
so just starting there
I have one other thing I have to do so
if we were to run this instead of
getting index out of bounds we would
actually get this message written now
now in order for me to test that I do
need to update one thing here so we did
rename the application from example one
so we need to change this to be our
calculator
[Music]
I need to name it the name of our class
so calculator location
you know calculator application
we need to make our variable a little
more uh readable uh ex makes no sense so
we know we want to reference the methods
in calculator application so really we
should just call it calculator
application uh calculate or application
so we know the method or we know the
class that we're calling
we know argument zero and argument two
are going to be left and right numbers
so we'll say 11 number
right number
uh argument one so one of the things we
can do is we can also do this so we can
pick in the values we can say spring
operator
to be clear
so we'll take operator
and we will set it equal to
args one
so now as we do our case statement we do
our switch on operator so if operator is
plus minus divide or multiplication we
know what methods we need to call so
then we're going to call calculator
application and instead of method one
we're going to do add two numbers
together
and instead of art zero and one we will
do the left number
and right now
now the beauty of this is if you've
named your application and your methods
clearly
especially your parameters if I were to
just
Say Hey I want to do uh this is where
the code completion comes in handy so I
can take calculator application add to
numbers and it will automatically pull
in the syntax from our methods so we
have the variable name left number and
right number so if we actually name
things the same name our our local local
variables the same everything translates
together everything is readable it flows
so we have this
so we have calculate application again
dot this is going to be a subtraction
calculator method
Dot slide
and then calculator method
or calculator application sorry multiply
and then last but not least so not a
valid
operator
so let me maximize this for readability
so we'll come back through here so we
have our document description for the
application it's going to be a
calculator application it's going to
have functions to simulate buttons on
the calculator right application was
started written by me uh started today
version one
our application name our method names
are very clear so we simulate Plus on a
calculator add two methods return the
results
our description add two numbers together
so we get two numbers we add them
together and we return the results of
those two numbers
same for mult uh for minus
divide and multiply now we'll get to the
rules in a minute but just follow me so
far
So based on how we've renamed this
everything is readable so even if we
were to delete our javadocs
the code is pretty straightforward it's
pretty readable pretty understandable so
if you come down here to the main method
now so even if we didn't have the
javadoc here just because we added this
method here or this is out this is
essentially that document
so if I try to run this as is
so now
we get our application is going to
accept three values simulate two numbers
and a math symbol being entered into a
calculator command calculate application
left number operator right number and it
tells you what needs to be passed in
because we didn't it through the
exception now we can handle that
exception
by simply returning
adding a return here
return
system
exit
zero
actually just do system.exit zero
system.exit zero exits the application
cleanly so now if we run this
we get our
message and we don't get the exception
but
um what we need to say is
um
I'm able to run command
syntax
and you can name this however you want
but just
um
you want to make it as descriptive as as
possible so applications kind of takes
up three values simulate two numbers
unable to run commands syntax should be
uh calculated application left operator
right number and then here are our
values
all right so we have our method we can
run it so if we actually get Pat get the
right values we should calculate the
operations
all right so to do that we need to go
into our run configuration
and set up some arguments so let's add
one plus one
and run
we get 2.0
if we run again
one minus one
we get zero
if we run again
1 divided by one
we get one and so on so as you can see
we can now run the application now to
thoroughly test the application we
should add some unit testing or other
test classes essentially that do what
simulate what I just did
um but other than that this is pretty
much how we self-document our code so
now if I look at here I can look at the
outline so I have my calculator
application I have my main I have add
two numbers divide two numbers multiply
subtract
uh if I were to
uh
way I can build the
Java Docs
there we are generate Java Docs
destination yep
Ducks finish yes to all
so it just generated the Java docs so if
I come out here
here's my documentation so if I open
with
web browser
so we have our clean Java docs or
whatever tool you use to generate docs
we have our package name we have our
project so we have our class calculator
application
brief description very clean easy to
understand go into the calculator
application so we calculate applications
uh have function to simulate buttons on
the calculator
since version author
here's our Constructors
we have our methods so main our
application is going to accept three
values
methods inherent from class
we have our Constructor
and we have our methods
oh that's what I
samples
when you generate Java docs you need to
include
there we go
there we go
so when you generate your javadocs you
can generate the ones for package
private static public because I did not
actually declare these as public they
were a class or package level
so when I regenerate it now we get our
additional method so there's add two
numbers divide two numbers multiply and
then here's our documentation
so to write readable code you can as you
can see basically it just means writing
code in plain English uh or whatever
language you're in you basically take
the what
the application or the program is
supposed to do and break it down into
its individual parts and then document
it accordingly or write your methods uh
variable names or even the calculations
in such a way that if you just read the
code you understand what that particular
piece of code is doing otherwise if you
start out with the initial example I had
it looks like spaghetti code very hard
to follow not real easy to test and as
you saw we really didn't even know what
the application was doing just by trying
to run it foreign
so let's go back over to the slides
so does anyone have any questions
is this how a developers when they bring
in a developer and they tell him that
hey please clean up this code is this
what they'll be doing like pretty much
going through each and every method to
see how can they make it simpler maybe
for the next developer or somebody
uh depending upon what they're actually
asking them to do yes
um it could be twofold one cleanup the
code could mean uh that you have very
complex methods uh where the
functionality of the method uh or the
program itself could be doing multiple
things so for instance uh say instead of
doing all the individual methods for uh
add divide multiply subtract maybe I had
a method that just said
um calculate numbers
and you passed in uh all three variables
uh float string float
but you really didn't know what
functionality really happened inside
that method but inside that method you
basically had all of this info uh all
this complex calculation so you had uh
oh okay so if it's left number do this
if it's or plus do this minus do this so
like this could have like all this code
could have been in one method so instead
of the system.outs where I call the
method all that functionality could be
in one method or program
and a lot of times when you're asked to
clean up code or refactor code what
you're doing is you're taking all these
complex uh
basically pieces of code which are
actually smaller pieces of code and you
break them down into their smaller uh
components like multiply divide
[Music]