DEV Community

Discussion on: I love to document my code. Am I doing it wrong?

Collapse
 
michaelgv profile image
Mike

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