Regarding code presentations

Any web or software developer (or engineer) frequently turns to the web as a resource for seeking help with a coding task, or learning something new.

Google can really be your friend when you feel stuck in the middle of a project and need assistance getting over a hump.

As a casual web developer for several years, I can’t even begin to count the number of times I’ve turned to the web for info that helped me achieve an objective in my personal creations.

At work, web searches have saved my butt in helping solve problems that expedited important content creation needs for our corporate website.

One thing that’s always essential is analyzing and understanding the code snippets you’ll always encounter when visiting the developer-related websites and blogs via your Google searches. If you find something useful for your needs, you’ll want to be able to bring it into your projects.

For this reason, proper presentations of code samples are always very helpful when they’re easy to read and analyze, especially at a quick glance when you’re in a rush and really need to grasp the info ASAP. I’ve always benefited from code that’s clearly presented, and simple to understand. And I’ve learned a lot just from examining code samples.

I’ve always admired web development sites and blogs with code snippets that are both presented beautifully and pleasing to the eyes – which of course translates to straightforward, quick, and efficient reading.

I’ve drawn a lot of inspiration from the creations of others offering great resources on web development. And I have used that inspiration as my motivation to share some insights of my own on this blog.

This always begins with great code presentations.

Ways to present code

If there ever were any definitive rules for presenting code on the web, the first would most certainly be that you want the code to clearly stand out from the main text on the page. For example, let’s see what some code would look like with no distinct formatting.

for (let l = 0; l < modClose.length; l++) {
    modClose[l].addEventListener(“click”, function() {
        this.style.display = “none”;
        document.body.classList.remove(‘noscroll’);
        bodyScrollLock.enableBodyScroll(this);
    });
}

The code is maybe OK to read, but it’s certainly far from ideal. Thankfully, you never see code presented this way. It’s conventional to present code in a monospaced font like Courier.

for (let l = 0; l < modClose.length; l++) {
    modClose[l].addEventListener("click", function() {
        this.style.display = "none";
        document.body.classList.remove('noscroll');
        bodyScrollLock.enableBodyScroll(this);
    });
}

For more distinction, it’s actually very common to find code sectioned off from the main content over a shaded background.

for (let l = 0; l < modClose.length; l++) {
    modClose[l].addEventListener("click", function() {
        this.style.display = "none";
        document.body.classList.remove('noscroll');
        bodyScrollLock.enableBodyScroll(this);
    });
}

This is basically good enough as far as presentation is concerned. But you can really take this further and make code look prettier, and arguably, even easier to read.

When I was learning to create things on the web, I stumbled across sites like CSS Tricks and really liked how they were displaying their code samples. So I took some direct inspirational cues and applied them here in creating my own presentation styling.

The first was to tweak out the styling toward making a real distinction from the main content, beginning with the content contrasted against a dark background.

for (let l = 0; l < modClose.length; l++) {
    modClose[l].addEventListener("click", function() {
        this.style.display = "none";
        document.body.classList.remove('noscroll');
        bodyScrollLock.enableBodyScroll(this);
    });
}

To make code stand out even more and make it easier to understand, you’ll frequently see what’s known as syntax highlighting, which color codes different types of syntax depending on the coding language. I’ve applied that here, with the help of a superb resource called Prism.js.

for (let l = 0; l < modClose.length; l++) {
    modClose[l].addEventListener("click", function() {
        this.style.display = "none";
        document.body.classList.remove('noscroll');
        bodyScrollLock.enableBodyScroll(this);
    });
}

Finally, to top it all off I added a banner to identify the coding language.

for (let l = 0; l < modClose.length; l++) {
    modClose[l].addEventListener("click", function() {
        this.style.display = "none";
        document.body.classList.remove('noscroll');
        bodyScrollLock.enableBodyScroll(this);
    });
}

Here’s another example with CSS code.

div.logoSection {
    position: absolute;
    font-size: 1px;
    left: var(--logoPadding);
    top: var(--logoPadding);
    z-index: 10; /* Logo will float over other content */
}

More considerations

If I had to define a rule for code presentations, it would most certainly be to allow others to copy and paste your code. After all, you want others to benefit from your work, just as you’ve similarly benefited.

Some sites display code snippets as bitmaps, unfortunately making copying and pasting impossible. This is because it’s way easier to just spit out an image of your work, usually via a plugin for your code editor. I see this on Medium or social media, because users have no control over visual text styling.

Another consideration is how you would present long lines of code. You can choose to either wrap them, or have the user scroll horizontally to see them.

// this line wraps
var ctx = document.getElementById(['cvChart', (index+1)].join('')).getContext('2d');
// this line wraps
var myChart = new Chart(ctx, chartConfig(x, 'Daily New Cases', ['7-Day Average', dataSets[stateID].name], [yavg, y], [movingAverageColor, dataSets[stateID].color], ['line', 'bar']));
// no line wrapping - scroll to see more
var ctx = document.getElementById(['cvChart', (index+1)].join('')).getContext('2d');
var myChart = new Chart(ctx, chartConfig(x, 'Daily New Cases', ['7-Day Average', dataSets[stateID].name], [yavg, y], [movingAverageColor, dataSets[stateID].color], ['line', 'bar']));

Generally, it’s just a matter of personal presence between the two. I probably see more of the latter.

Summary

Developers always use the web as an important reference for help and learning. For them, proper presentation of code is very important. To be useful, code needs to be clear and easy to read. I’ve learned a lot by examining code snippets, and I’ve always wanted to share my web development insights through my own code presentations.