It is known that we read more code than we write, so documentation is super important and when done well can be a time saver. But what's a good solution for this? This talk shows how easy it is to take tests and use them as a live documentation of your code, because they're always up to date.

1. Yael Zaritsky Perez, Software Developer @ Wix
Software Developers, Communicate
Your Intentions!
(TL;DR: Do it Using Tests)
yaelz@wix.com twitter@zaritskyPe_yael linkedin/yael-zaritsky-perez github.com/yaelz

2. About
me
00

3. Wix Engineering
Locations
Ukraine Israel Lithuania
VilniusKiev
Dnipro
Tel-Aviv
Be’er Sheva
Haifa

4. AGENDA
Communicate? Why?
Communicate? What?
Methods of Communication
Examples
Summary

5. Communicate?
Why?
01

6. Communicate
Why?
Robert C. Martin's quote about this

7. Communicate
Why?

8. New
FeaturesBugs
Communicate
Why?
We work on existing codebase

9. Don’t touch what
already works
Communicate
Why?
and need to feel comfortable to touch it
We work on existing codebase

10. Communicate
Why?
… also, we are not alone

11. Communicate?
What?
02

12. Communicate
What?
Libraries, APIs Inner Parts

13. Methods of
Communication
03

14. #1Documentation
Methods of
Communication
You don’t have to
change it
Usually outdated

15. Methods of
Communication
#2Verbal communication
We don’t remember
Not for everyone
No one stays forever

16. Methods of
Communication
#3Types
Add to the system
Can’t explain edge cases
Can’t tell a story

17. Methods of
Communication
#4Tests
Already there (?)
Live documentation

18. Using tests to communicate.
Examples
04

19. Example #1
Tests can tell a story

21. describe('Feed’, () => {
it('should render a single blog post’, () => {...})
it('should filter by ...’, () => {...})
})

22. How quickly can
you understand
this?
it('should render a single blog post', async () => {
nock(baseURL).get('/experts-blog-posts')
.reply(200, [{ title: 'My epic blog post title', id:
13 }])
const { wrapper } = setup({})
const tab = queryByTestId(wrapper, 'feed-tab')
fireEvent.click(tab)
sideNavBarDriver.feedTab().click()
const feedDriver = feedDriverCreator(wrapper)
await expect(
queryByTestId(componentWrapper, `blog-post-
header-13`).textContent)
.toContain(‘My epic blog post title’)
})

23. it('should render a single blog post', async () => {
nock(baseURL)
.get('/experts-blog-posts')
.reply(200, [{ title: 'My epic blog post title', id: 13 }])
const { wrapper } = setup({})
const tab = queryByTestId(wrapper, 'feed-tab')
fireEvent.click(tab)
await expect(
queryByTestId(componentWrapper, `blog-post-header-13`).textContent)
.toContain(‘My epic blog post title’)
})
Before

24. it('should render a single blog post', async () => {
nock(baseURL)
.get('/experts-blog-posts')
.reply(200, [{ title: 'My epic blog post title', id: 13 }])
const { wrapper } = setup({})
const tab = queryByTestId(wrapper, 'feed-tab')
fireEvent.click(tab)
await expect(
queryByTestId(componentWrapper, `blog-post-header-13`).textContent)
.toContain(‘My epic blog post title’)
})
Before
Part 1

25. it('should render a single blog post', async () => {
nock(baseURL)
.get('/experts-blog-posts')
.reply(200, [{ title: 'My epic blog post title', id: 13 }])
const { wrapper } = setup({})
const tab = queryByTestId(wrapper, 'feed-tab')
fireEvent.click(tab)
await expect(
queryByTestId(componentWrapper, `blog-post-header-13`).textContent)
.toContain(‘My epic blog post title’)
})
Before
Part 2

26. it('should render a single blog post', async () => {
nock(baseURL)
.get('/experts-blog-posts')
.reply(200, [{ title: 'My epic blog post title', id: 13 }])
const { wrapper } = setup({})
const tab = queryByTestId(wrapper, 'feed-tab')
fireEvent.click(tab)
await eventually(async () => {
expect(
queryByTestId(wrapper, ‘blog-post-header-13’).textContent)
.toContain(‘My epic blog post title’)})
})
Before
Part 3

27. Now,
Let’s Refactor it

28. it('should render a single blog post on feed', async () => {
nock(baseURL)
.get('/experts-blog-posts')
.reply(200, [{ title: 'My epic blog post title', id: 13 }])
const { wrapper } = setup({})
const tab = queryByTestId(wrapper, 'feed-tab')
fireEvent.click(tab)
await eventually(async () => {
expect(
queryByTestId(wrapper, ‘blog-post-header-13’).textContent)
.toContain(‘My epic blog post title’)})
})
Refactoring...

29. Refactoring...
nock(baseURL)
.get('/experts-blog-posts')
.reply(200, [{ title: 'My epic blog post title', id: 13 }])
makeBlogPostServerReturn([
{ title: 'My epic blog post
title', id: 13 }
])
Part 1

30. Refactoring...
const { wrapper } = setup({})
const tab = queryByTestId(wrapper, 'feed-tab')
fireEvent.click(tab)
const { wrapper } = setup({})
const sideNavBarDriver = sideNavBarDriverCreator(wrapper)
sideNavBarDriver.clickOnFeedLink()
Part 2

31. Refactoring...
Part 3
expect(queryByTestId(wrapper, ‘blog-post-header-13’).textContent)
.toContain(‘My epic blog post title’)
const feedDriver = feedDriverCreator(wrapper)
await expect(feedDriver.getTextForBlogPostHeader(13))
.toContain(‘My epic blog post title’)

32. it('should render a single blog post', async () => {
const wixBlogPost = createDisplayBlogPostWith({ id, title })
makeBlogPostServerReturn([wixBlogPost])
const { wrapper } = setup({})
const sideNavBarDriver = sideNavBarDriverCreator(wrapper)
sideNavBarDriver.clickOnFeedLink()
const feedDriver = feedDriverCreator(wrapper)
await expect(feedDriver.getTextForBlogPostHeader(id)).toContain(title)
})
Refactoring...

33. it('should render a single blog post', async () => {
const wixBlogPost = createDisplayBlogPostWith({ id, title })
makeBlogPostServerReturn([wixBlogPost])
const { wrapper } = setup({})
const sideNavBarDriver = sideNavBarDriverCreator(wrapper)
sideNavBarDriver.clickOnFeedLink()
const feedDriver = feedDriverCreator(wrapper)
await expect(feedDriver.getTextForBlogPostHeader(id)).toContain(title)
})
After

34. Example #2
Breathing Documentation

35. const getImageUrlsFromImgNames = imageNameArr =>
imageNameArr
.map(imageName => nameToImageUrlMap[imageName])
.filter(imageUrl => imageUrl)
It may seem redundant...

36. describe('getImageUrlsFromImgNames', () => {
.
.
.
it('should filter out imageNames that don’t exist in map', () => {
imageFilter.initMap({ anImageName: 'http://www.someImageUrl.jpg' })
const imageNameArray = ['imageNameNotInTheMap']
expect(imageFilter.getImageUrlsFromImgNames(imageNameArray)).toEqual([])
})
})
Now it’s clear

37. Time to
Wrap
05

38. Using Tests as
Documentation
Worth our time
Live documentation
Tells the story
Explains edge cases
Prevents mistakes

39. Live documentation
Tells the story
Explains edge cases
Prevents mistakes
Using Tests as
Documentation
Worth our time
Saves
It’s just a state of mind

40. “Any fool can write code that a computer
can understand. Good programmers write
code that humans can understand.“
-- Martin Fowler

41. Thank You
yaelz@wix.com twitter@zaritskyPe_yael linkedin/yael-zaritsky-perez github.com/yaelz

42. Q&A
yaelz@wix.com twitter@zaritskyPe_yael linkedin/yael-zaritsky-perez github.com/yaelz

43. Sources
Clean Code (pdf)
Software Devs, communicate your intentions (Blog post)
yaelz@wix.com twitter@zaritskyPe_yael linkedin/yael-zaritsky-perez github.com/yaelz