Writing Self-Documenting Code
We're excited to be teaming up with Hired to bring you career insights about diversity, inclusion, and the job market.
Writing clear, understandable code for complex systems can be a challenge for software developers or students learning to code. This can be intimidating when learning to code, but as an ally in the programming community, we’ll walk you through a way to make your coding more understandable. In this post, we’ll explore the concept of self-documenting code as a technique for writing clearer code.
What is self-documenting code?
Self-documenting code is code that doesn’t require code comments for a human to understand its naming conventions and what it is doing. It utilizes descriptive method and variable names that resemble human speech. You may understand this concept even if you’ve not heard the term before. Other synonymous names include “human-readable code” and “self-describing code.”
Why is it useful?
Writing understandable code is hard:
- People think and solve problems in different ways
- Systems are complex and sometimes require workarounds or unintuitive solutions
- Not everyone contributing to a codebase has the same context about the entire system
- Comments and documentation can become outdated
Self-documenting code aims to solve these issues by encouraging code that clearly states its intent in common language.
Tic-tac-toe: A self-documenting code example
The good news is that writing self-documenting code can be very intuitive, because it mimics the way that we naturally think. To give an example of how we can refactor code to be more self-documenting, let’s use the childhood game of tic-tac-toe.
Intro
For those unfamiliar with the game, it works as follows: There is a 3 x 3 grid and two players, ‘X’ and ‘O’. The two players take turns marking spots on the grid. The first player to mark three spots in a straight line wins the game.
I’ve written a preliminary implementation below. The code is pretty short, and the game is fairly simple. However, upon first glance, you might wonder, “What the heck is happening here?” Even for such a straightforward program, the code takes a moment to grok.
Refactoring strategy
So how can we make this code easier to read, understand, and maintain? I’ll use the following refactoring technique:
- Identify functionally significant, independent pieces of code
- Extract these pieces of code into methods with human-readable names
- Repeat until all code is sufficiently human-readable
Let’s start here with the take_turn
method:
Specifically, let’s take a look at the first three lines of code above. This chunk of code appears to deal with error checking. Great! Let’s extract that out into its own method and name it something descriptive:
Looking better already!
But we’re not quite done with the error checking code yet. We can make this even more readable. Let’s try some more refactoring:
With a couple simple extractions, the error checking code is now even more readable:
There isn’t much more code that can be pulled out of here, so let’s return to take_turn
:
The next chunk of code has a lot going on. What exactly is it doing? It appears to be marking the spot with the current player’s symbol, decrementing the number of empty spaces, and swapping players in preparation for the next turn. So, let’s update the code to say just that:
Now:
Let’s tackle the final chunk of code:
For fun, let’s also go ahead and refactor the game_won?
method:
Before:
After:
Not bad! The new code is much easier to read and understand. If we want to know the specifics of what the methods are doing, we can visit the definitions. We now also have a better idea of what the developer intended for the methods to do, which makes it easier to spot bugs or make modifications.
An added bonus: better tests
We’ve now seen how self-documenting code can make programs easier to read and understand. However, self-documenting code can also make programs easier to test. Self-documenting code encourages developers to write many small, single-function methods, rather than larger, multi-functional monolithic methods. In addition to being easier to understand, these smaller methods are also easier to test. This is because the input and output spaces for these smaller methods is more constrained than in the larger, more complex methods.
As an example, try to imagine all of the tests that you would need to write to comprehensively test take_turn
. It’s pretty difficult to enumerate all of the possible input and ouptut conditions that you’d need to test for to ensure full coverage. Now, for comparison, imagine the tests that you’d need to write to fully test mark_spot!
or switch_players!
. Much easier, right? Since the purpose of each of these methods is very narrowly defined, the input and output spaces are also much simpler to enumerate. This pattern results not only in better test coverage, but also clearer tests that serve as additional documentation regarding the intent of the code.
Conclusion
Writing understandable code is hard. Even the smallest programs, as demonstrated by the original tic-tac-toe code above, can be difficult to follow. This, of course, does not bode well for the building of large, complex, multi-contributor systems. However, using the principles of self-documenting code can help! Even if you already have code that isn’t self-documenting, the good news is that it is relatively painless to transform existing code into self-documenting code. This can be done by iteratively extracting portions of code into single-use and single-line methods with descriptive names. In this way, even the most complex code can be quickly converted into self-documenting code that is clearer and easier to understand.
If you’re ready to start your coding journey, check out the courses we offer in our all-women learning environment here at Hackbright Academy.
About the author: Leah Dorner is a software developer on Hired’s Candidate Experience team. Prior to Hired, Leah worked as a software developer on Twitter’s Product Security team. When not writing code, Leah enjoys eating ice cream, wearing onesies, and spending time outdoors (perhaps even all at the same time). Leah finds it odd writing about herself in the third person.
This piece was originally published on Hired’s Tech Careers Blog. Hired is a marketplace that matches tech talent with the world’s most innovative companies. Learn more here.
Recommended Reading
The 10 Best Software Engineering Blogs
RELATED POSTS
Recent Posts
- February 04, 2021 Change Your Career at a Software Engineering Bootcamp
- January 29, 2021 What Can I Do with Python? Tips and Tricks
- January 26, 2021 3 Ways a Coding Bootcamp Can Help You Become a Software Engineer
- January 22, 2021 Is a Python Bootcamp Worth It?
- January 15, 2021 Software Engineers Get Real About Imposter Syndrome
CATEGORIES
- News (161)
- Hackbright Academy (123)
- Hackbright News (106)
- Profiles of Woman Engineers (105)
- Alum (98)
- Engineering Advice (68)
- tech (54)
- career change (53)
- Resources (49)
- TGIF (49)
- link roundup (49)
- reading (49)
- recap (49)
- roundup (49)
- weekly (49)
- women in tech (43)
- Becoming A Software Engineer (36)
- Software Engineer (36)
- female software engineers (36)
- diversity in tech (35)
- change the ratio (32)
- learn to code (31)
- Career Services (30)
- Admissions Office (28)
- women who code (28)
- #ilooklikeanengineer (27)
- Student Blogs (25)
- Hackbright Field Trips (24)
- female engineers (24)
- Python (23)
- coding (23)
- Hackbright Mentors (22)
- Thought Piece (21)
- Video (21)
- partner (20)
- diversity (18)
- Recruiting & Hiring (16)
- alumna (14)
- Software Engineers (13)
- hackbright (13)
- tech inclusion (13)
- hired (11)
- how to become a software engineer (11)
- Graduation (10)
- changetheratio (10)
- Tech Talk (9)
- software developer (9)
- Imposter Syndrome (8)
- hiring (8)
- Course Report (7)
- Facebook (7)
- GitHub (7)
- Hackbright Alumnae Showcase (7)
- Mentorship (7)
- Scholarship (7)
- women engineers (7)
- coding bootcamp (6)
- Hackbright mentor (5)
- Liz Howard (5)
- Programming Languages (5)
- Scholarships (5)
- mentor (5)
- recruiting (5)
- Admissions (4)
- Eventbrite (4)
- Full-Stack (4)
- Graduates (4)
- Hackathon (4)
- Heroku (4)
- Melanie Warrick (4)
- Mentors (4)
- Nicole Zuckerman (4)
- Resume (4)
- Silicon Chef (4)
- developer (4)
- holidays (4)
- instructor (4)
- women in computer science (4)
- Ada Lovelace Day (3)
- Chris Palmer (3)
- Code of Conduct (3)
- GoDaddy (3)
- Google (3)
- Halloween (3)
- Interview Tips (3)
- Jasmine Tsai (3)
- Job Search (3)
- Kathryn King (3)
- Mica Swyers (3)
- Negotiation (3)
- Pat Poels (3)
- STEM (3)
- Shilpa Dalmia (3)
- code (3)
- coding school (3)
- computer programming (3)
- day in the life (3)
- day-to-day (3)
- engineering (3)
- girls in tech (3)
- holidaze (3)
- international women's day (3)
- learning (3)
- part-time (3)
- prep (3)
- “Kelley Robinson” (3)
- ActivityHero (2)
- Aimee Morgan (2)
- Alyson La (2)
- Angie Chang (2)
- Arduino (2)
- Change.org (2)
- Elissa Murphy (2)
- Financing Options (2)
- Girls Who Code (2)
- Gowri Grewal (2)
- Gulnara Mirzakarimova (2)
- Hackathons (2)
- Inspiration (2)
- Joyce Park (2)
- Julia Grace (2)
- Julia Hartz (2)
- Kate Heddleston (2)
- Katherine Fellows (2)
- Katherine Hennes (2)
- Lisa Lee (2)
- Liz Crawford (2)
- Machine Learning (2)
- Marissa Mayer (2)
- Meagan Gamache (2)
- Megan Speir (2)
- Michelle Glauser (2)
- Michelle Sun (2)
- Natalie Downe (2)
- New Relic (2)
- Niniane Wang (2)
- Padmasree Warrior (2)
- Poornima Vijayashanker (2)
- Programming (2)
- Rebecca Bruggman (2)
- Security Engineering (2)
- Selina Tobaccowala (2)
- SheCodes (2)
- Siena Aguayo (2)
- SurveyMonkey (2)
- Tindie (2)
- Uber (2)
- Uncategorized (2)
- Web Apps (2)
- Zendesk (2)
- Zoe Kay (2)
- almnae (2)
- back-end (2)
- bootcamp (2)
- career transition (2)
- careers (2)
- coding blonde (2)
- computer programmer (2)
- ebook (2)
- engineer (2)
- financial aid (2)
- gender (2)
- gender gap (2)
- gift guide (2)
- hackbright prep (2)
- jobs after bootcamp (2)
- payment plans (2)
- podcast (2)
- product management (2)
- projects (2)
- python 101 (2)
- python programmers (2)
- reddit (2)
- social impact (2)
- students (2)
- techhire (2)
- technical product management (2)
- white house (2)
- women (2)
- women in STEM (2)
- #HackentinesDay (1)
- #hackdisrupt (1)
- #learntocode (1)
- 2017 (1)
- A Day In The Life Of A Hackbright Student (1)
- Academia.edu (1)
- Ada Lovelace (1)
- Adora Cheung (1)
- Affectiva (1)
- Alison Gianotto (1)
- Allison Deal (1)
- Ambassadors (1)
- Ambassadors Program (1)
- Anna Billstrom (1)
- AppJamming (1)
- Ashley Lorden (1)
- Automate Everything (1)
- Bay Area Girl Geek Dinners (1)
- BeMyApp Factory Hack (1)
- Belinda Runkle (1)
- Bessie Chu (1)
- Big O Notation (1)
- Bills.com (1)
- Birchbox (1)
- Black Girls Code (1)
- Blameless Work Culture (1)
- Brittany Martin (1)
- Browser Extension (1)
- Buffer (1)
- B’Elanna Torres (1)
- CODE Documentary (1)
- CODE2040 (1)
- CTO (1)
- CTOs (1)
- Cara Marie Bonar (1)
- Career Day (1)
- Cathy Edwards (1)
- Charmy Chhichhia (1)
- Chegg (1)
- Chomp (1)
- Christian Fernandez (1)
- Christina Liu (1)
- Christina Pan (1)
- Christine Yen (1)
- Cisco (1)
- Clare Corthell (1)
- Code.org (1)
- CodeGirl (1)
- CodeShannon (1)
- Computer Security (1)
- Conferences (1)
- Costumes (1)
- Couchsurfing (1)
- Cynthia Dueltgen (1)
- Danica McKellar (1)
- Data (1)
- Data Science (1)
- Dave-To-Girl (1)
- Dave-To-Girl Ratio (1)
- DevBeat 2013 (1)
- Dominic Dagradi (1)
- Electric Imp (1)
- Email Signature (1)
- Emily Gasca (1)
- Engineering Culture (1)
- Erica Kwan (1)
- Erin Parker (1)
- Farnaz Ronaghi (1)
- Female CTOs (1)
- Femgineer (1)
- Future of Food Hackathon (1)
- Gayle Laakmann McDowell (1)
- Gemma Barlow (1)
- Go Against The Flow (1)
- Google I/O 2014 (1)
- Grace Hopper (1)
- Grace Hopper Celebration (1)
- Hacbright Academy (1)
- Hack Your Life (1)
- Hack(bright) for Good (1)
- Hackbright Girl Geek Dinner (1)
- Hackbright engineering fellow (1)
- Hardware (1)
- Harvey Mudd College (1)
- Homejoy (1)
- Hour of Code (1)
- Huffington Post (1)
- Hypatia (1)
- Indiegogo (1)
- Industry Insight (1)
- Ingrid Avendaño (1)
- Jason Huggins (1)
- JavaScript (1)
- Jibe (1)
- Job Seeker (1)
- Jocelyn Goldfein (1)
- Joel Franusic (1)
- Kat Hagan (1)
- Kate Matsudaira (1)
- Katherine Wu (1)
- Katie Miller (1)
- Kaylee (1)
- Kelsey Yocum (1)
- Kimber Lockhart (1)
- Ksenia Burlachenko (1)
- LAUNCH Hackathon (1)
- Lauren Antonoff (1)
- Leap Motion (1)
- Lindsay Cade (1)
- LinkedIn (1)
- LinkedIn Profile (1)
- Lise Meitner (1)
- Lookout Mobile Security (1)
- Louise Fox (1)
- Maia Bittner (1)
- Margaret Le (1)
- Margaret Leibovic (1)
- Maria Klawe (1)
- Mariane Abou-Jaoudé (1)
- Marie Curie (1)
- Marissa Marquez (1)
- Martha Kelly (1)
- Math (1)
- Matt Haines (1)
- Mattermark (1)
- Meebo (1)
- Megan Anctil (1)
- Meggie Mahnken (1)
- Mercedes Coyle (1)
- Minted (1)
- Moms in Tech (1)
- Morgan Griggs (1)
- Mozilla (1)
- Music Information Retrieval (1)
- NCC Group (1)
- NESTA (1)
- Natasha Litt (1)
- Nidhi Kulkarni (1)
- Night Classes (1)
- Nishita Agarwal (1)
- Noah Kindler (1)
- Node (1)
- Node.js (1)
- Noise (1)
- O’Reilly (1)
- PandaWhale (1)
- Parse (1)
- Part-time classes (1)
- Perforce (1)
- PickAxe Mobile (1)
- Pinterest (1)
- Platform API (1)
- Popforms (1)
- Powers of Two (1)
- Presidential Innovation Fellow (1)
- Programming Interviews Exposed (1)
- PyCon 2014 (1)
- Quirky Eggs (1)
- Raji Arasu (1)
- Rana el Kaliouby (1)
- Raspberry Pi (1)
- Rebecca Parsons (1)
- RocksBox (1)
- Rosalind Franklin (1)
- Rosette Diaz (1)
- Ruby (1)
- Ruby on Rails (1)
- Sandra Lerner (1)
- Sandy Jen (1)
- Sarah Allen (1)
- Sarah Mei (1)
- Science and Technology (1)
- Security Engineer (1)
- Selenium (1)
- Shannon Burns (1)
- She Started It (1)
- Shiv Kumar (1)
- Smithsonian (1)
- Software Testing (1)
- Spitfire Athlete (1)
- Square (1)
- Stephanie Shupe (1)
- Steve Tjoa (1)
- StubHub (1)
- Student (1)
- Tech Gives Back (1)
- Testing (1)
- The Developers (1)
- ThoughtWorks (1)
- Tom Croucher (1)
- Toxicity (1)
- Tracy Chou (1)
- Twilio (1)
- TwilioQuest (1)
- Twitter (1)
- Velocity Conference 2014 (1)
- Vida Ha (1)
- Warren Colbert (1)
- Washington DC (1)
- Web Developer (1)
- Wendy Saccuzzo (1)
- Women TechMakers (1)
- Work Culture (1)
- Zainab Ghadiyali (1)
- Zed Shaw (1)
- ada (1)
- all-women (1)
- alumna spotlight (1)
- alumnae (1)
- alumni (1)
- app (1)
- be brave get paid (1)
- bias (1)
- black leaders (1)
- blog (1)
- bloomberg (1)
- career strategist (1)
- catalyst (1)
- checkr (1)
- codecademy (1)
- coderpad (1)
- coding interviews (1)
- collaborative coding (1)
- conference (1)
- corporate (1)
- costume (1)
- documentaries (1)
- edie windsor (1)
- education (1)
- efective communication (1)
- employer sponsorship (1)
- engineers (1)
- entrepreneur (1)
- fall2014 (1)
- fellowship (1)
- female founders (1)
- field trip (1)
- finance (1)
- fintech (1)
- firebase (1)
- front-end (1)
- genentech (1)
- getting started (1)
- girl power (1)
- git (1)
- giving back (1)
- gynopedia (1)
- hack bright (1)
- hacker (1)
- hacksmart2018 (1)
- implicit bias (1)
- infographic (1)
- information security (1)
- infosec (1)
- integration (1)
- internship (1)
- interviews (1)
- intro to programming (1)
- jobhunting (1)
- kids code (1)
- leadership (1)
- lesbians who tech (1)
- lwt (1)
- notifica (1)
- onboarding (1)
- online python 101 (1)
- pair programming (1)
- phenomenal woman (1)
- pre-bootcamp (1)
- programmers (1)
- python web framework (1)
- run the world (1)
- salary (1)
- salary negotiation (1)
- san francisco (1)
- security consulting (1)
- self-documenting code (1)
- sf (1)
- sheroes (1)
- software engineering fellowship (1)
- south bay (1)
- starting your own business (1)
- startup (1)
- streak (1)
- superheroes (1)
- tech tips (1)
- technical interview (1)
- technologies (1)
- transition (1)
- tuition (1)
- unconscious bias (1)
- volunteering (1)
- work-life balance (1)
- wwc (1)
- zach haehn (1)
- zapier (1)
- “Versal” (1)