Published on

Advent of Pull Requests Best Practice - Day 11

  • avatar
    Nico Prananta
Advent of Pull Requests Best Practice - Day 11

There's something super crucial you gotta keep in mind when reviewing a pull request: documentation. It's like the bread and butter of software development, whether you're flying solo or in a team. Documentation saves the day for anyone who's gonna work on your code in the future (including you when you've forgotten what you did six months ago).

Here's a quick rundown of what to look for in the PR's documentation:

  • Updated Docs Check: Make sure the PR is not just about code; it should also update or add the necessary documentation. This could be anything from README updates, code comments, API docs, to user manuals.
  • Clarity and Completeness: Ask yourself: Is the documentation easy to get? Does it cover all the new stuff without missing a beat? Like, if there's a new API endpoint, the docs should clearly explain what it's for, how to use it, its parameters, and what it returns.
  • Technical Truths: The documentation should be a mirror reflection of the code. It's gotta accurately describe how the features actually work, including any quirky bits.
  • Sticking to Standards: Every project has its own style. The documentation should match this – whether it's about formatting, tone, or style.
  • Future-Proofing: Think about the next person who'll read this. Good documentation should give them the lowdown on why the code is the way it is, how it works, and how they can play around with it or improve it.
  • Examples for Real: Where it makes sense, nudge for examples in the documentation. They can be lifesavers in making complex stuff clear.
  • Inline Comments Matter: For the twisty-turny parts of the code, inline comments are gold. They should give the why and how of the decisions made in the code.
  • External Links: If the PR is dealing with stuff like third-party APIs or libraries, the documentation should be a good tour guide – providing the right links and references.

That's about it. Keeping these in mind will make sure your PR reviews are not just about the code but also about making life easier for everyone who comes after you.

Happy coding!

📖 Early Bird Offer

Need more insights like this? Jump on our early bird offer and grab your copy for 40% less! This deal is flying off the shelves, so hurry! 🎉