Skip to content

Instantly share code, notes, and snippets.

@lawrencewalters
Created September 16, 2014 16:47
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save lawrencewalters/2497526908599e2b4e32 to your computer and use it in GitHub Desktop.
Save lawrencewalters/2497526908599e2b4e32 to your computer and use it in GitHub Desktop.
level up rails Ruby Basics answers
Explain how the Five Second Rule for code review works.
The five second rule is the concept that if you can't understand the intent of a line of code or method in 5 seconds
then it is likely that item is too complex, and needs to be broken down into more easily understandable components.
Knows why comments lie, and how to write self-documenting code
The phrase "comments lie" refers to the fact that because comments are not a part of the working application,
they are never tested, reviewed, or used in production. Because of this, as bugs are found, or enhancements
are made, the functionality is verified, but the comments are never validated in any consistent way. Thus,
there is no feedback loop to pressure us to update comments as they deviate from ongoing code chantes.
We explain our code adequately by writing code that makes its intent clear. This mostly relates to
how we name things and keeping individual methods and classes simple, ideally following the single
responsibility pattern.
This is the crux of self documenting code - you can read it almost like english, and just the act of
reading it will tell you what it is doing.
Knows why comments lie, and how to write self-documenting code
I would argue comments are necessary in foundational libraries. For example, the ruby API itself has tons
of documentation built into it in comments because these are the building blocks. For example, without
documentation on #inject, no one would have any idea how to use it. It's not a simple concept, and the
format in which it appears in code is not always completely clear. With a short definition in a comment,
we can now all speak the same language, understanding #inject wherever we see it.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment