question-mark
Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

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
  };

Issue Analytics

  • State:closed
  • Created 6 years ago
  • Reactions:4
  • Comments:5 (4 by maintainers)

github_iconTop GitHub Comments

1reaction
dchill-sagecommented, Apr 7, 2017

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.

0reactions
jamimecommented, Apr 7, 2020

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.

Read more comments on GitHub >

github_iconTop Results From Across the Web

Getting Started with JSDoc 3
A quick-start to documenting JavaScript with JSDoc. ... JSDoc 3 is an API documentation generator for JavaScript, similar to Javadoc or phpDocumentor.
Read more >
JSDoc-Style-Guide - GitHub
Intro. This style guide intends to use the most minimal set of JSDoc tags while maintaining a good standard of documentation for even...
Read more >
Google JavaScript Style Guide
9 Appendices: 9.1 JSDoc tag reference: 9.2 Commonly misunderstood style rules ... A JavaScript source file is described as being in Google Style...
Read more >
JSDoc comments | WebStorm Documentation - JetBrains
JSDoc comments are used for documentation lookup with Ctrl+Q in JavaScript and TypeScript, see JavaScript documentation look-up and TypeScript ...
Read more >
JSDoc Reference - TypeScript: Documentation
What JSDoc does TypeScript-powered JavaScript support? ... deprecated values are typically displayed in a strike-through style like this .
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Dev.to Post

No results found

github_iconTop Related Hashnode Post

No results found