Strategies for documenting code

Documentation aims at explaining how the code works, and how to use it.

Let's look at some ways to document your code:

• comments :- put some comments (something is better than nothing), because it would helpful for your future self, and others who are going to work on it.

• providing images, block schemes, diagrams, links and references to cool reference, where it's explained more in details (might be place from where you learned it.)

• README files containing all the necessary information about code utilization

• release notes/changelogs will help developer to get where the stuff is heading toward what is the recent progress.

Pros & Cons

Documenting your code is an important skill to have, some need to practice it, and some born with it.

Pros

• Saves time, when you next time need to make changes to it.
• helps to refresh your memory
• helps to fix bugs
• allows for version control
• Helps others to go deep into your code, and motivates them to contributes.

Cons

• takes a lot of time and patience to write good documentation.
• easily becomes outdated, so needs to be updated all the time
• constant feedback is needed to make it genuinely good which is usually hard to get, for small teams.
• Boring!!!

Comments

[Aaron Reese]

Proper naming of variables, classes and functions can reduce the need for comments. If you still need them explain why (not how). Comments tend to become stale faster than code as the code gets refactored and an inaccurate comment is worse than no comments.

[John Carroll]

Proper naming of variables, classes and functions can reduce the need for comments. If you still need them explain why (not how)

+1 to this.

I found this article by Adam Nathanial Davis incredibly valuable for describing what good, readable code looks like. I highly recommend it if someone wants to improve their code readability.

Edit:
As an example of this philosophy put into practice, I was just writing the following javascript code (the comment I've added doesn't exist in the original code):

const channelGroupDocsAssociatedWithThisChannel =
  channelGroupDocs.filter(
    (doc) => doc.id in channelDoc.channelGroupIds,
  );

const orgMembershipDoc = orgMembershipDocs.find((orgMembershipDoc) => {
  // In this case, the intermediate variable acts purely as a form
  // of documentation to make the code more readable.
  const isTheOrgOfThisInviteAssociatedWithThisChannel =
    channelGroupDocsAssociatedWithThisChannel.some(
      (channelGroupDoc) =>
        channelGroupDoc.organizationId ===
        orgMembershipDoc.organizationId,
    );

  return isTheOrgOfThisInviteAssociatedWithThisChannel;
});

[Ido Schacham]

some need to practice it, and some born with it.

Nobody is born with it, everyone needs to practice. I've been developing for over 20 years and I'm still improving my documentation skills - not to mention that the documentation style and technology keep evolving, so there's always something more to learn.

One thing that helped me a lot is the book On Writing Well. It has precise and very practical writing advice that can help you to become an all around better writer.

When it comes to technology, Storybook has proved as a fantastic tool to document frontend components. Instead of writing lots of text that could easily become outdated, Storybook creates a visual and usable documentation from the components themselves.