DEV Community

loading...
Cover image for Writing documentation for your React Components

Writing documentation for your React Components

Maher Alkendi
Developer from the [O] 🇴🇲
・2 min read

Speak with any developer that has worked in a team or on a large coding project and they will tell you that one of the most important things you could do as you build you application is writing documentation.

To understand why, simply build an app then come back to the code a month from now and see how lost you will get even though you wrote the code.

Now while writing documentation sounds like a great idea, it isn't the easiest thing to do. Developers are often pressured by time or sometimes you just don't feel like writing an essay about your code.

If you develop in React and you don't document your code at all then start by simply documenting your React components only. Get in that habit and go from there. In this article, I will write down some items that you can consider as checkpoints anytime you write a React Component. Try as much as possible to do this for all your components and it will become a habit.

Description/Purpose of the component

What does this component do?

Answer that question and you are done with the first step. This is a good place for pictures of what the component should look like in the browser.

Example:

...
const DeleteButton = () => {...}
...

# Description:
# This component will delete an item when pressed. 

Something as simple as that one line will go a long way. This just happens to be a simple example but for a more complex component, it will be very helpful.

List all props

Just have a table with all props that the component has. In addition, mention what type of value it is expecting.

Example:

const DeleteButton = ({ element, isPermanent }) => {...}
Prop Description type
element element we want to delete String
isPermanent Should we archive or delete from db? Boolean

List all components

If your component uses any other components, then list them. List the ones that are from external libraries as well.

import ExternalComponent from 'ExternalLibrary'

const DeleteButton = ({ element, isPermanent }) => {
...

return (
  <ButtonWrapper>
   ...
   <ExternalComponent />
   ...
  </ButtonWrapper>
 )
}
Component Description
ButtonWrapper Sets the button layout
ExternalComponent Does something cool

That is all. If you are like me and find it difficult to fit documentation into your development flow, then try the steps in this article as a start. Let me know how it works out! I will be using this on a real project and do plan to write a follow up article with an update and better examples.

If you have any more ideas, share in the comments!

Ok! Now back to learning 👨🏿‍💻

Discussion (2)

Collapse
engrajibulhasan profile image
MD Rajibul Hasan

Helpful

Collapse
williamhatch profile image
william

Using storybook might be a better idea...