I'm currently building some HTML with JS (specifically using the jQuery library). My code is as follows:

goToError: function (error, returnView, returnController, callback) {

    this._transitionOutPanel(function () {

    var loadError = function () {

        (function buildErrorHtml() {
            var ctrlDiv = $('<div></div>', {
                style: "text-align: center;"

            var ctrlP1 = $("<p></p>", {
                html: ("An error occured while loading this view.<br><b>Error code:</b> {0} ({1})").format(error.status, error.statusText)

            var ctrlP2 = $("<p></p>").appendTo(ctrlDiv);

            var ctrlBackBtn = $("<button></button>", {
                html: "Back",
                class: "btn btn-danger"
            ctrlBackBtn.click(function () {
                if (returnView != null && returnController != null) {
                    navigation.go(returnView, returnController);
                } else {
                    navigation.go("Login", "Accounts", null, "Login");


        navigation._transitionInPanel(function () {
            if (typeof callback === "function")


More specifically, my question is in regards to when it is best to use a comment vs a function expression for code clarity. I currently have a self-invoking function expression named buildErrorHtml() that constructs the HTML and appends it to the relevant element on my page.

Would this be better outside of a function expression (amongst the rest of the code in var loadError = function() { ... }) or should it be as it is, inside an anonymous function? I've been told to only use comments to tell readers 'why' instead of 'what', and I don't feel using a comment is justified with this criteria.

The alternative is using a comment like so:

// Build HTML
var ctrlDiv = $('<div></div>', {
    style: "text-align: center;"

Which method tells anybody reading my code what it is the code is doing best?

Feedback on anything else is also greatly welcome.

  • \$\begingroup\$ Remove the comment from the second example and you're done. What you're doing is not all that unusual. \$\endgroup\$ – Greg Burghardt Nov 27 '15 at 21:35
  • \$\begingroup\$ That was my initial thought, although when I took a step back and tried to figure out what the code was doing from somebody else's point of view I felt like it either needed to be commented or given its own function. Perhaps I'm wrong :) I'm looking for utopia here really. \$\endgroup\$ – Aaron Yarborough Nov 27 '15 at 21:38
  • \$\begingroup\$ I feel like anybody who's familiar with jQuery will immediately recognize what building HTML looks like, and a "Build HTML" comment or buildErrorHtml function name won't really make much of a difference . \$\endgroup\$ – Peter Olson Nov 30 '15 at 2:48

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Browse other questions tagged or ask your own question.