Why Well Commented Code Is Important? Jsdoc Approach

As you probably know the JSDoc is a popular approach for inline documentation used in many programming languages.

Let’s take a lok at the best practices, to start well commenting create a comment using two leading asterisks then describe your function.

/**
 * Log a string, used for debugging
 */
function log ( string ) {
    console.log( string );
}

Why well commented code is important?

Ok, because is pretty an maintainable! Check the code snippet bellow and try to uderstand the options. This is an example of contact form configuration.

var simple_forms = new SimpleForms("#contact-form", {
    theme: "white",                      
    style: "underline",                  
    ajaxSubmit: true,                    
    validate: true,                      
    tooltips: true,                      
    debug: true,                         
    consent: true,                       
});

As you can see there may be some misunderstanding of what each option exactly does, for example the option tooltips what is this for ? Or what are the other available values for theme option ?

And now check the well commented version of the code above.

var simple_forms = new SimpleForms("#contact-form", {
    theme: "white",         // form color theme, options: white | dark | purple | red | green | blue | faded-light | faded-dark
    style: "underline",     // form fields style, options: none | underline | classic | classic-rounded | modern | modern-rounded
    ajaxSubmit: true,       // send form using AJAX (no page reload)
    validate: true,         // enable form fields validation
    tooltips: true,         // show validation errors as tooltips, if false will show errors as strings bellow the field
    debug: true,            // enable debugging mode (will show errors in browser console)
    consent: true,          // enable submit button after consent checkbox is checked
});

Now each option has a description and this saves time to setup things quickly! The code abovee is just an example for better understanding why well commented code is gold.

Can I escape documentation ?

Ok, what’s obvious to you may not be obvious or even confusing to someone else while reading your code. Documenting helps a lot  while working in a team, it makes the work process faster and easier for each team member.

The answer here is “You can” but better spend some time to arrange your code.

Thanks for your time,
Best regards. Lucas.