Skip to main content

weekly-engineering-meeting-4-11-comments-documentation-and-practical-example-of-reacting-pickers-at-powr

Weekly engineering meeting 4 11: Comments, documentation and practical example of Reacting pickers at POWr​

Commenting your code

In an ideal scenario code does not need comments, variable names are clear enough to make it readable. However there are few cases in which comments are useful, couple listed here

  1. The code is doing something unusual to handle some specific weird edge case scenario or an out-of-project-scope note. Eg:
// update this at some point - didn't want to rewrite everything for react yet
  const triggerPremiumClick = () => {
    window.handleTriggerPremiumClick();
  }
  1. There is some dynamic code which does not specifically mention the use case someone would search for Eg: experiments that test different site builders. In this case searching shopify trial would be useless, and some comments are useful.
  2. Documenting use of a function/component used in several places which has some required and optional arguments to list what is required and what is optional and what are defaults if optional args are not passed.

Note: if your comment is single line - add it to codebase, if it is an essay - add to git wiki and link the wiki page as a comment.

Practical example of Reacting pickers at POWr

Document to look at : https://github.com/superpowr/powr/wiki/Creating-React-Components-for-POWr-Settings

Copy pasta template : https://github.com/superpowr/powr/wiki/React-component-starter

Sample code built : https://github.com/superpowr/powr/tree/feature/text-component-react