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] because I've actually seen applications where this makes sense to pull this out and do this but this code itself was embedded inside of another method or another class and if you refactor things cleanly it's reusable the whole point of object-oriented programming is to write clean reusable functional code so that you don't reinvent the wheel every time you do a new method new class new program and if you break it down like this it's very easy to understand what's going on and able to follow the balancing ball okay gotcha okay this is uh as Michael had mentioned as he started getting into this this actually you could do a lot of discussion around documentation and that the approach that he he's lined out is is one approach um and it varies from organization organization and even language language because some kind of you know some places it's um it's things like it's entirely write your code without comment so that there are no comments it should be fairly it should be readable based on uh like function names and class names and variable names and things like that and some of it is um even without having things quite as as complicated like the way hit this one's set up for example you know the subtract two numbers and return the result if you look at the the variable names it's it's obvious that's what it is I mean it's like you basically just take left number minus right number and it returns result so the code itself is is very readable even with a very simple um name now some cases the names you know there are some languages limit the names um and some of them uh some organizations are going to say hey we want to keep it you know shorter rather than longer code completion makes it so that it doesn't that is less of an issue uh like personally I prefer to have stuff within the comments as opposed to you know having the name basically describe what it does it can be like a summary but um usually have more in the comments versus uh you know having real long uh variable names and things like that but the key to the point for all that is consistency and so he he mentioned several times you know programming standards development standards that is probably the most important thing is that whatever organization you're in is that everybody does it consistently which is where things like code reviews are huge so for example if I if if this is the the standard and I go in and write it and I don't follow the standard and I you know I've got some x's and y's and some things like that and some really short you know cryptic names then in the code review would be something where Mike would be like hey you know according to code standards this is how it should look so you know your code doesn't fall as standard let's get that to standard so that when because that's the most frustrating thing is when somebody comes in and looks at the code and depending on what class or what file or what function even it's completely different uh how it's documented and of course the other thing you have to watch out it for is just make sure that it stays current you know if you come in and you start changing something around then you may need to you know update the comments you may need to make sure that you've got your you know maybe you adjust a couple of the uh the names um so that's important and then one other thing I want to point out that's that sort of comes up as Michael was going through that where he was looking at you know like where he's building out like what this does and what it returns uh particularly like the the divide by zero that's something where it's important for both testing and as you're developing and so now it says hey you know we can't divide by zero so you should either you know have some sort of exception that it throws or have something that says okay if I get a zero I'm going to send this message or return this value and then make sure that your code does that because from a testing point of view that means you know they're gonna they're gonna come through and they should be able to see uh from your comments from your documentation how that's supposed to work and then build that test and then it better match results so if you say it's going to return uh not a number then when they come in if they do a zero then it should come back not a number otherwise you're gonna say hey this failed testing so documentation not is is a great way for you to be more thorough in your development that's why in some cases there's there's some approaches to coding where you start by creating comments you pseudocode everything and sort of write out the story of what your class or your function is supposed to do and then as you build in the code you've sort of got like an outline that says hey I got to do this I've got to do that I've got to check for these things and handle these exceptions I'm going to return these kinds of messages so there's there's a lot of benefit that comes from proper documentation that is this sort of hidden you know there's a couple things Michael highlighted but there's there's some things that were just sort of like uh you know a part of that that when you think about it like oh wow this is really going to help us become better developers doing it uh oh one last thing I want to mention is that while this was focused on Java and javadoc uh just like unit testing the junit we've mentioned in the past those tools exist in some way form or fashion in almost every language and if you if you're not sure what it is like you know if you're getting into something new then if you just do a Google or other search based on you know hey what is the javadoc equivalent in PHP um or c-sharp or whatever it is then you're gonna you're probably gonna get some good results and yeah the um the way that you do comments and maybe the way that you uh take advantage of that tool are going to vary but uh you know those those tools pretty much exist everywhere and it's worth doing a little bit of upfront research to make sure that whatever it is you're you're working in that it um that you take advantage of it and it I guess the follow-up to that is things like uh Minify and things like that and some of the code compilation types of things that work for for example with JavaScript which allow you to have really big complex names and all of that and not be hurt by uh when you get to run time because it basically goes through and says I'm going to take all these big complex very human readable names I'm going to turn on something that is just you know the machine can read it a human's not going to get much use out of it but then it's it's going to run faster so um you know there's some tools like that whichever environment you're in it's worth it to understand what tools are there and as an organization or even as an independent is to I have a standard and stick to it and hold yourself and your teammates to it I'll step off my soapbox but there's just like I said this is one of those it's actually it's a very big uh topic and although Michael did a great job and you know in one session sort of like saying hey here's here's some big differences from where he started and then where he ended up um there's so many rabbit holes we could go down talking about that yep and I have planned on possibly a future topics and discussions on that as well but it good addition Rob uh also you know you mentioned code review well right here this is a good example of what should be caught in a code review if you document it so here I'm saying what this method should be doing and I say oh I'm done I commit the code under code review it should fail because I did not follow this condition I did not do the divide by zero rules so this would fail this should come back and then what should have happened should have been something more along the lines of okay so if right number equals zero it's either return a number um or like throw or format exception or null number or whatever but basically you have to do something like this to handle that uh like Rob was saying uh the other thing that uh Rob mentioned that I didn't touch on too deeply but if you actually were to like I said remove these comments you understand what the code's doing but if you I haven't written this and you're just writing it for the beginning this makes sense to just come in and write something write the requirements for the method right like pseudocode the method and then even potentially uh after this so you do something like this and actually let's just uh do another example real quick um so if we were to do something like this um simulate the factorial on a calculator and this is to uh calculate the factorial value of a number thank you now you get a number so we could say float we could say factorial and we'll say float and number that's it all right so we don't have to go too far into the depths except we know we need to return something so we know we need to return a float uh oh uh sorry wrong all right so float float and we'll just do return all right so this is just meeting the bare minimum requirements for the method and then in here we could essentially kind of do some pseudo code or you could kind of write your testing so you would say something like for testing you could do something inside of here even but for like a unit test and this kind of pushes a different topic but this is kind of where you would write your test driven code so you would write the test cases first and then come back and make sure that the code worked but to test this it would be factorial of say zero would equal zero um Victoria one two equal one factorial two would equal two three is going to be six and then for testing basically factorial and factorial is going to equal to n times n minus 1. and so what you end up getting into is oh well all right here is how we're going to test this this is how the function should work so you would actually write this test case to expect these values and then you would come back in here and you would write the code to do this so actually what you're going to be doing here is if number equals zero return one else return this one zero so now what we've essentially done is to meet this criteria we are checking the number to see if it's zero if it's zero we return one and then so if we start out with zero uh oops uh factorial zero should be if one return one um I'll change the code here just for Simplicity for example so if we're one we return one so one one yeah no sir was right so if we're one one minus one is zero zero comes in for zero we return one uh if we're two two minus one okay um what am I doing wrong here something number times the factorial thank you or well yeah yeah right something like that but anyway so this is how you would write recursion but here's your test case you would actually write this test and then the test would exist so you would expect one two three and so on and then you would come in here and write your code so if your code worked you would run the test and you should get these these test cases should pass so that's just kind of pseudocoding and expanding out on that but if I didn't do that or like this division by zero here like this rule code review should fail things like that so this just is like Rob said one example of how you can do readable code uh I just like this particular approach because with the comments it's very clear without the comments it's still pretty clear as to what's going on and this can be applied to pretty much any language out there not just Java any other questions okay so today we talked about writing readable code we talked about ways we could uh cleanly write code why it's beneficial what can happen if we don't write readable code and just some other rabbit holes we could go down if we expand on this topic further I'd like to thank everyone for your time today we appreciate your time we'd love if you'd love to discuss any of these topics further with us you can reach out with some questions or comments to us at infoletdeveloper.com developmenter.com contact us we're on Twitter at developreneur we're also on facebook.com at developer and you can find us on YouTube by searching developreneur our goal is making every developer better thank you have a wonderful day thank you
Transcript Segments
thank you
[Music]
because I've actually seen applications
where this makes sense to pull this out
and do this but this code itself was
embedded inside of another method or
another class and if you refactor things
cleanly it's reusable the whole point of
object-oriented programming is to write
clean
reusable functional code so that you
don't reinvent the wheel every time you
do a new method new class new program
and if you break it down like this it's
very easy to understand what's going on
and able to follow the balancing ball
okay gotcha okay
this is uh as Michael had mentioned as
he started getting into this this
actually you could do a lot of
discussion around
documentation and that the approach that
he he's lined out is is one approach
um and it varies from organization
organization and even language language
because some kind of you know some
places it's
um it's things like it's entirely write
your code without comment so that there
are no comments it should be fairly it
should be readable based on
uh like function names and class names
and variable names and things like that
and some of it is
um even without having things quite as
as complicated like the way hit this
one's set up for example you know the
subtract two numbers and return the
result if you look at the the variable
names it's it's obvious that's what it
is I mean it's like you basically just
take left number minus right number and
it returns result so the code itself is
is very readable even with a very simple
um name
now some cases the names you know there
are some languages limit the names
um and some of them uh some
organizations are going to say hey we
want to keep it you know shorter rather
than longer code completion makes it so
that it doesn't that is less of an issue
uh like personally I prefer to have
stuff within the comments as opposed to
you know having the name basically
describe what it does it can be like a
summary but
um usually have more in the comments
versus uh you know having real long uh
variable names and things like that but
the key to the point for all that is
consistency and so he he mentioned
several times you know programming
standards development standards that is
probably the most important thing is
that whatever organization you're in is
that everybody does it consistently
which is where things like code reviews
are huge so for example if I if if this
is the the standard
and I go in and write it and I don't
follow the standard and I you know I've
got some x's and y's and some things
like that and some really short you know
cryptic names then in the code review
would be something where Mike would be
like hey you know according to code
standards this is how it should look so
you know your code doesn't fall as
standard let's get that to standard so
that when because that's the most
frustrating thing is when somebody comes
in and looks at the code and depending
on what class or what file or what
function even
it's completely different uh how it's
documented and of course the other thing
you have to watch out it for is just
make sure that it stays current you know
if you come in and you start changing
something around then you may need to
you know update the comments you may
need to make sure that you've got your
you know maybe you adjust a couple of
the uh the names
um so that's important and then one
other thing I want to point out that's
that sort of comes up as Michael was
going through that where he was looking
at
you know like where he's building out
like what this does and what it returns
uh particularly like the the divide by
zero that's something where it's
important for both testing and as you're
developing and so now it says hey you
know we can't divide by zero
so you should either you know have some
sort of exception that it throws or have
something that says okay if I get a zero
I'm going to send this message or return
this value and then make sure that your
code does that because from a testing
point of view that means
you know they're gonna they're gonna
come through and they should be able to
see uh from your comments from your
documentation how that's supposed to
work and then build that test and then
it better match results so if you say
it's going to return uh not a number
then when they come in if they do a zero
then it should come back not a number
otherwise you're gonna say hey this
failed testing so documentation not is
is a great way for you to be more
thorough in your development that's why
in some cases there's there's some
approaches to coding where you start by
creating comments you pseudocode
everything
and sort of write out the story of what
your class or your function is supposed
to do and then as you build in the code
you've sort of got like an outline that
says hey I got to do this I've got to do
that I've got to check for these things
and handle these exceptions I'm going to
return these kinds of messages so
there's
there's a lot of benefit that comes from
proper documentation that is this sort
of hidden you know there's a couple
things Michael highlighted but there's
there's some things that were just sort
of like
uh you know a part of that that when you
think about it like oh wow this is
really going to help us become better
developers doing it uh oh one last thing
I want to mention is that while this was
focused on Java and javadoc
uh just like unit testing the junit
we've mentioned in the past
those tools exist in some way form or
fashion in almost every language and if
you if you're not sure what it is like
you know if you're getting into
something new then if you just do a
Google or other search based on you know
hey what is the javadoc
equivalent in PHP
um or c-sharp or whatever it is then
you're gonna you're probably gonna get
some good results and yeah the
um the way that you do comments and
maybe the way that you uh take advantage
of that tool are going to vary but uh
you know those those tools pretty much
exist everywhere and it's worth doing a
little bit of upfront research to make
sure that whatever it is you're you're
working in that it um
that you take advantage of it and it I
guess the follow-up to that is things
like uh Minify and things like that and
some of the code compilation types of
things that work for for example with
JavaScript which allow you to have
really big complex names and all of that
and not be hurt by uh when you get to
run time because it basically goes
through and says I'm going to take all
these big complex very human readable
names I'm going to turn on something
that is just you know the machine can
read it a human's not going to get much
use out of it but then it's it's going
to run faster so
um you know there's some tools like that
whichever environment you're in it's
worth it to understand what tools are
there and as an organization or even as
an independent is to
I have a standard and stick to it and
hold yourself and your teammates to it
I'll step off my soapbox but there's
just like I said this is one of those
it's actually it's a very big uh topic
and although Michael did a great job and
you know in one session sort of like
saying hey here's here's some big
differences from where he started and
then where he ended up
um there's so many rabbit holes we could
go down talking about that
yep and I have planned on possibly a
future topics and discussions on that as
well but it good addition Rob uh also
you know you mentioned code review well
right here this is a good example of
what should be caught in a code review
if you document it so here I'm saying
what this method should be doing and I
say oh I'm done I commit the code under
code review it should fail because I did
not follow this condition I did not do
the divide by zero rules so this would
fail this should come back and then what
should have happened should have been
something more along the lines of okay
so if
right number
equals zero
it's either return
a number
um
or like throw
or
format exception or
null number or whatever but basically
you have to do something like this to
handle that uh like Rob was saying uh
the other thing that uh Rob mentioned
that I didn't touch on too deeply but if
you actually were to like I said remove
these comments you understand what the
code's doing but if you I haven't
written this and you're just writing it
for the beginning this makes sense to
just come in and write something write
the requirements for the method right
like pseudocode the method and then even
potentially uh after this so you do
something like this
and actually let's just uh do another
example real quick
um so if we were to do something like
this
um
simulate
the factorial on a calculator
and this is to uh
calculate the factorial
value of a number
thank you
now
you get a number so we could say float
we could say factorial
and we'll say float
and number
that's it all right so we don't have to
go too far into the depths except we
know we need to return something
so we know we need to return
a float
uh oh uh sorry wrong
all right so float
float
and we'll just do return
all right so this is just meeting the
bare minimum requirements for the method
and then in here we could essentially
kind of do some pseudo code or you could
kind of write your testing so you would
say something like for testing
you could do something inside of here
even but for like a unit test and this
kind of pushes a different topic but
this is kind of where you would write
your test driven code so you would write
the test cases first and then come back
and make sure that the code worked but
to test this it would be factorial
of say zero
would equal zero
um
Victoria one
two equal one
factorial two
would equal two
three
is going to be six
and then
for testing
basically factorial and factorial is
going to equal to n times n minus 1.
and so what you end up getting into is
oh well all right here is how we're
going to test this this is how the
function should work so you would
actually write this test case to expect
these values and then you would come
back in here and you would write the
code to do this so actually what you're
going to be doing here is if
number
equals zero
return
one
else
return
this one
zero
so now what we've essentially done is to
meet this criteria we are checking the
number to see if it's zero if it's zero
we return one and then so if we start
out with zero uh oops uh factorial zero
should be
if one return one
um
I'll change the code here just for
Simplicity for example so if we're one
we return one so one one yeah no sir was
right
so if we're one one minus one is zero
zero comes in for zero we return one
uh if we're two two minus one okay
um
what am I doing wrong here something
number times the factorial thank you
or
well yeah yeah
right
something like that but anyway so this
is how you would write recursion but
here's your test case you would actually
write this test and then the test would
exist so you would expect one two three
and so on and then you would come in
here and write your code so if your code
worked
you would run the test and you should
get these these test cases should pass
so that's just kind of pseudocoding and
expanding out on that but if I didn't do
that
or like this division by zero here like
this rule
code review should fail things like that
so this just is like Rob said one
example of how you can do readable code
uh I just like this particular approach
because with the comments it's very
clear
without the comments it's still pretty
clear as to what's going on and this can
be applied to pretty much any language
out there not just Java
any other questions
okay
so today we talked about writing
readable code we talked about ways we
could uh
cleanly write code why it's beneficial
what can happen if we don't write
readable code and just some other rabbit
holes we could go down if we expand on
this topic further
I'd like to thank everyone for your time
today we appreciate your time we'd love
if you'd love to discuss any of these
topics further with us you can reach out
with some questions or comments to us at
infoletdeveloper.com
developmenter.com contact us we're on
Twitter at developreneur we're also on
facebook.com at developer and you can
find us on YouTube by searching
developreneur our goal is making every
developer better
thank you have a wonderful day
thank you