re: I love to document my code. Am I doing it wrong? VIEW POST

FULL DISCUSSION
 

I've always done development like so, take this inherited code:

import { UserAction, ProfileValidator } from '@internal-package/ui-workflow/tools/UserAccount';

class IsAdministrator extends UserAction {
    /** @rt.inject "UserProfile" **/
    private _validator: ProfileValidator = null;
    public validate(): boolean {
        return this.getValidator().getPermissionLevel(7777))
    }
}

export default IsAdministrator;

This is pretty self explanatory, but then take this example:

import { Action, FormElement } from '@internal-package/ui-workflow/tools/Actionables/Elements';

export default class UxEnhancementAction extends Action {
    private _v: FormElement = new FormElement( this );
    public set( n: Action.Node ): void {
        this._set( n.build() ).write( this._v.__setter.write, { props: true, val: !this._v.__getter._wv } );
    }
}

Obviously, the second code block is confusing. If we break it down by documenting, it looks like this:

/**
 * This is legacy code, it should be removed in Version 0.3.1
 */
import { Action, FormElement } from '@internal-package/ui-workflow/tools/Actionables/Elements';

/**
 * This class was used to enhance the button actions, we wanted nested button actions, now these are not required
 */
export default class UxEnhancementAction extends Action {
    /** This is a form element **/
    private _v: FormElement = new FormElement( this );
    /** Set the node, build the node's DOM tree (n.build), write it by passing in the FormElement's write function, and inherit the properties (props: true), then set the success value of the FormElement's write value (wv). REFACTOR NOTE: This should be renamed for clarity if we need to keep this method alive. - DEVNAME **/
    public set( n: Action.Node ): void {
        this._set( n.build() ).write( this._v.__setter.write, { props: true, val: !this._v.__getter._wv } );
    }
}

My attitude: If your code is self explanatory, you don't need long documentation. If it's confusing, write some longer docs. but, don't write no documentation, always document even if it's minimal

code of conduct - report abuse