Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

RFC: Block comments at top of classes #4

Open
YodaDaCoda opened this issue Jun 16, 2021 · 0 comments
Open

RFC: Block comments at top of classes #4

YodaDaCoda opened this issue Jun 16, 2021 · 0 comments

Comments

@YodaDaCoda
Copy link
Member

It's not uncommon to have a block comment at the top of a class, added at the time of creation, describing the intention of the class and including a section for changes. The usefulness of most these comments tends to be short-lived, as they're not updated and people move on from the project. A more accurate representation of the information can generally be obtained through the use of git blame.

Example:

/******************************************************************************************
* Created By     :  William Brockhus
* Release        :  v1
* Description    :  This class does some things and stuff
*
*   Modification Log:
*     -----------------------------------------------------------------------------
*     Developer                          Date               Description
*     ----------------------------------------------------------------------------
*     William Brockhus                   2021-06-16         Created
* *****************************************************************************************/

If such a block must be included, keep to the minimum information necessary, and consider using jsdoc tags as they add highlighting.

Example:

/**
 * @description This class does some things and stuff
 */
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant