JSDoc style

Can we create a styleguide, provide guidance to people building UI in React/Carbon as to how and when to document their code.

Here’s some examples of how i have decided to document my React code but can we get together, agree and write this up and share so the wider community can benefit and adopt a style:

# method example
  /**
   * Opens the dialog
   *
   * @param {String} reportIdentifier - unique identifer for the report
   * @param {Object} filterData - the filter data from the store
   * @method openDialog
   * @return {Void}
  */
  openDialog: (reportIdentifier, filterData) => {

# Class example
/**
 * This store is used for exporting reports.
 *
 * The store structure is:
 * {
 *   dialog_open: true/false,
 *   report_identifier: the report key e.g. income_statement,
 *   filter_data: The filter from the store,
 *   exported: true/false,
 *   fileType: The exportation file type
 *   paths: url paths for all the reports e.g. csv_path, pdf_path
 *   success_message: the success message when report has been exported successfully
 * }
 *
 * @class FinancialStatementStore
 * @constructor
 */
class ReportExportStore extends Store


/**
 * @public
 * @class ReportExportDialog
 * @classdesc Main view that renders the report export dialog.
 * @example
 * The dialog is typically invoked from an onClick event of a <Button>.
 * Make sure you pass into it a report_identifier and any additional params e.g. filter from your store.
 *
 * <Button
 *   columnAlign="right"
 *   as={ 'primary' }
 *   onClick={ ReportExportActions.openDialog.bind(this, this.financialStatementType, this.store.get('filter')) }
 * >
 *   { I18n.t('actions.export') }
 * </Button>
 */
class ReportExportDialog extends React.Component {

# props
  static propTypes = {
    /**
     * Object containing the remote reports from your store.
     *
     * @property reports
     * @type {Object}
     */
    reports: React.PropTypes.object.isRequired
  };

[dchill-sage]

While the idea of self-documenting code is lovely, and I believe we should write Carbon code with this ideal in mind, I do not find it sufficient for large-team maintenance of said code. Whether we’re talking about Ruby or React or any other language/technology, all too often there are specific details, such as props and method/function parameters which require explanation to facilitate quick and safe modification and maintenance of the code at hand. As a developer, if I need to change the way a function works, I need to know what it is intended to do, and often what exactly to expect in its props and/or arguments. Will that parameter be a Map or an Array, or could it be either? Does this component property have a default value? Does the return of the function carry any special meaning?

The better (and more consistently) original authors document the code, the less analysis and guesswork is required before modifying it. In my view, this applies equally to private methods as to public ones. The outside visibility of a method has no bearing on my need to thoroughly understand it before engaging in editing.

That being said, I would like to point out that this discussion probably needs to be centered more on Carbon/React code in repositories like GAC, and less so on the Carbon library itself. Given that a dedicated team predominantly writes our Carbon components, which are meant to be consumed elsewhere (and also by public 3rd parties), I think this topic is less critical for the Carbon repo itself. Then again, there is an argument to be made for a consistent policy across all Sage One javascript code. In short, I’m not looking to necessarily push the Carbon team into a particular code commenting practice, but I would like to see one established for surface-level Carbon code with the input of the Carbon team.

[jamime]

I think this applies more to class-based components, as we move to functional components it it becomes less relevant, for Carbon at least.

I agree that in places we need for some level of documentation, however, JSDoc often results in meaningless comments like this:

/**
 * OnClick handler
 *
 * @param {Event} e - onClick event
 * @method onClick
 * @return {Void}
 */
onClick: function onClick(e) {}

Generally, I’d encourage clean code over documenting complex code and I wouldn’t mandate the comments unless we were using it to publish documentation which we are not.

I’m happy with our current approach, document where needed and prefer clean code above all.