contributors: @Sebastian Coates @Cecelia Crumlish

Commenting

type	use
JSDOc: / … /	explain module, if the module is very small and local, this is unnecessary
inline //	commenting in line to make things easier

JSDoc /** ... **/ // for modules and components 
//line comments

JsDoc comments

/**
* @<insert your cool JSDoc comments here> 
**/
TextSayHelloTo = (name: string) => {
	return (
				<Typography>Hello {name}</Typography>
	);
}

use JSDoc	no need
exported component used in other modules	local component function that is called only once or twice
component/function that is complicated and requires elaboration	simple component function
component/function that is used more than twice in a single module (even if local )	App.tsx component

main idea:

JSDoc comments are supposed to make life easier, only use them when you feel like your code is going to be complicated to decipher

we use typescript, so explaining @params and @returns is unnecessary (unless the name or type alone is not enough to understand the purpose of a value)
if you decide do use the JSDoc comments, choose elaborate on what they mean on a higher level

//bad
/**
 * @name LogbookLevelBar
 * @param  data[] 2d array of data // of what?
 * @param pointsDisplayed, number // what does this do? Typescript will tell us this
 * @param ...props for VictoryBarProps // typescript will tell us this
 * @returns a Log Levels bar // what is that?
 */

//good althought alot of info feel free to get rid of some of the params

/**
 * @name LogbookLevelBar
 * @param  data[] 2d array of data for the LogbookLevelBar to display
 * @param pointsDisplayed default to 7 points displayed 
 * @param ...props optional override for VictoryBarProps
 * @returns a Log Levels bar that will display the week leading up 
 *          to the most recent entry, if data[] is empty
 *          the LbLB will display an empty message
 */

in-line comments

no rule of thumb here just use when it seems necessary

useful tags:

//TODO: when something has yet to be completed, implemented, written
//NEEDSWORK: something is broken or buggy but you need help or to return to this late