Archive for the ‘Programming’ Category

File Under: Programming

The Best Way to Comment Your Code

The Voynich Manuscript was very poorly commented. Image: Wikimedia

We’ve written before about the value of writing your README before your code, but what about when it comes to the actual code? Terse one-liners? Paragraph-long descriptions? How much is enough and when is it too much?

How to comment code is a perennial subject of debate for programmers, one that developer Zachary Voase recently jumped into, arguing that one of the potential flaws with extensive comments (or any comments really) is that they never seem to get updated when the code changes. “We forget,” writes Voase, “overlooking a comment when changing the fundamental behavior of semantics of the code to which it relates.”

Voase thinks the solution is in our text editors, which typically “gray out” comments, fading then into the background so we can focus on the actual code. We ought to do the opposite, he believes: Make the comments jump out. Looking at the visual examples on Voase’s post makes the argument a bit more compelling. Good text editors have configurable color schemes so it shouldn’t be too hard to give this a try and see if it improves your comments and your code.

Another approach is to treat comments as a narrative. Dave Winer recently mentioned comments in passing, writing about the benefits of using an outliner to handle comments since it makes it easy to show and hide them:

Another thing that works is the idea of code as a weblog. At the top of each part there’s a section where each change is explained. The important thing is that with elision (expand/collapse) comments don’t take up visual space so there’s no penalty for fully explaining the work. Without this ability there’s an impossible trade off between comments and the clarity of comment-free code. No manager wants to penalize developers for commenting their work. With this change, with outlining, that now works.

Winer has an example you can check out if you’d like to see it in practice (and a screenshot of how it looks in the actual editor). Winer is also a proponent of what he calls Narrate Your Work, publishing a running story of his work.

Donald Knuth, author of the seminal book, The Art of Computer Programming, advocated a similar narrative approach with what he called Literate Programming. Literate programming seeks to weave comments and docs out of a “literate” source.

Then there’s the opposite school of thought that says your code should always be so clear and so obvious as to never need comments. See Slashdot for quite a few people advocating this approach, most of whom we suspect have never had to go back and read through their code again years after it was written.

The best way to comment your code is up to you, but whichever path your team decides to follow the best advice is to make sure you take the time to actually have a plan for comments. The most useless comments are haphazardly written, which also makes them unlikely to be updated when the code changes. There are as many approaches as there are programmers; just make sure you actually settle on one and stick with it. Down the road, when it’s time to update that older code you’ll thank yourself.

GitHub Changes Make It Easier to Track Your Favorite Projects

Image: GitHub.

Code sharing giant GitHub has rolled out some significant changes to the site’s notifications system, making it easier to keep track of interesting projects without being notified of every single change.

GitHub has always made it easy to “watch” a project, which means you’re notified whenever there are any updates. Now the company has added another level of watching, dubbed “stars,” to the mix. As GitHub’s Kyle Neath writes on the company blog, “stars are a new way to keep track of repositories that you find interesting.”

When you star a project you can keep track of it, but you won’t be notified of every change. Think of starring a project on GitHub as a more casual way of watching, the equivalent of bookmarking it for later. To make it easier to do that, every repo now has a star button next to the familiar watch button.

The big difference between watching and starring a project comes down to notifications. If you are watching a repository, you will receive notifications for all discussions — project issues, pull requests, comments on commits and any other comments. If you’re not watching a repo you’ll just receive notification for the discussions you participate in.

The other main thing worth noting is that any repositories you were previously watching can now be found on your stars page. If you want to go back to watching them, you’ll need to change them over yourself. There’s also a new auto-watch feature; when you’re given push access to a repository GitHub automatically adds it to your watch list.

GitHub has a few other changes rolling out along with the new stars feature, including improved notification e-mails. Be sure to check out the GitHub blog for the full details on everything that’s new.

File Under: CSS, Programming

Write Better CSS With ‘Idiomatic CSS’

If you’ve ever worked on a large programming project you know all about the joy of trying to read other people’s code. And of course that’s how everyone else feels about reading your code. That’s why formal programming style guides exist — to help bridge the gap between individual styles.

There is no right or wrong style of writing code, but there are styles that are easier to read and share with other people. Search the web and you’ll find formal guides to writing readable JavaScript, Python, Ruby and countless other popular languages, but one language that doesn’t get as much attention is CSS.

Developer Nicolas Gallagher wants to change that. To do so Gallagher has put together Idiomatic CSS, a style guide for how to format, organize and craft quality CSS that anyone can work with. Here are the general principles of the project:

“Part of being a good steward to a successful project is realizing that writing code for yourself is a Bad Idea™. If thousands of people are using your code, then write your code for maximum clarity, not your personal preference of how to get clever within the spec.” — Idan Gazit

  • All code in any code-base should look like a single person typed it, no matter how many people contributed.
  • Strictly enforce the agreed upon style.
  • If in doubt use existing, common patterns.

Idiomatic CSS follows in the footsteps of Rick Waldron’s Idiomatic JS, which does the same thing for JavaScript.

If you’ve made the leap to a CSS preprocessor like SASS or LESS, fear not, Idiomatic CSS has you covered as well. Preprocessor syntax varies and Idiomatic CSS offers examples in SCSS, but the more general rule, “your conventions should be extended to accommodate the particularities of any preprocessor in use,” apply to others as well.

Wrangling CSS on large projects can be a pain, but if you take the time to create a set of conventions and ensure that everyone sticks to them it becomes a much more manageable task. If you’ve got experience and insight to share, head on over to the Idiomatic CSS GitHub page and contribute your knowledge.

File Under: CSS, Programming, Web Basics

Learn to Code by Watching Others Write It

Five years ago the hotness in web development was showing what you could create without resorting to Flash. Now it seems the same is true of JavaScript. While we’ve nothing against JavaScript, the increasingly powerful tools in CSS 3 mean that JavaScript is no longer a necessity for building cool stuff on the web.

The latest JavaScript-free demo we’ve run across is this very cool stopwatch demo made using only CSS 3, no images or JavaScript necessary. Now before you dive into the code and get all Karl Van Hœt on us, yes, there is a script used to handle CSS prefixing, but the actual stopwatch doesn’t require it to work.

But what caught our eye even more than the JavaScript-free stopwatch demo is the tutorial that accompanies it. The tutorial — which is one part screencast and one part code dump — is part of Code Player, which helps you learn how to do things by showing you the code as it’s written. It’s an interesting tutorial method, one we haven’t seen before.

Watching code being written isn’t for everyone, especially beginners who might not be able to easily follow what’s happening, but it’s well suited to those that already understand the basics and just want to see how some particular function was written. It also provides an interesting look at how other developers work, which in turn might teach you a new trick or two.

The Code Player offers a variety of playback speeds depending on how fast you want to run through the tutorial, and there’s a timeline scrubber for pausing and rewinding any bits you miss. Our only complaint is that Code Player forces focus in the browser; when you try to click another tab or do something in the background Code Player steals focus back immediately.

If learning something new by watching someone else type sounds intriguing, head on over to the Code Player site. And don’t worry if the stopwatch demo has no appeal for you, there are plenty of other tutorials to choose from.

File Under: Programming

Learn to Code With Mozilla’s ‘Thimble’ Editor

Mozilla Thimble is a new web-based code editor, part of the company’s recently unveiled “Webmakers” project. Thimble is designed to give novice webmakers an easy-to-use online tool to quickly build and share webpages.

You can check out Thimble over at the new Mozilla Thimble website. Keep in mind that Mozilla hasn’t formally launched Thimble; the company is still testing, fixing bugs and iterating the app.

Thimble is slightly different than other online code editors you may have tried, putting the emphasis on teaching HTML to newcomers rather than catering to advanced users. Thimble offers side-by-side code editor and code output panels which help new users see immediate results. Type an <h1> and you’ll immediately see a headline. The instant feedback is not only helpful for spotting and fixing errors, but encouraging for those just starting out since you can see what you’ve created right away.

Thimble is very purposefully not aimed at veteran HTML junkies, but for those just learning how to write HTML — which is the focus of the Webmakers project — Thimble is one of the friendliest, easiest-to-use code editors we’ve seen.

Thimble can also load pre-made project templates to help users get started with some content that’s ready to build on. Currently the featured projects section of the Thimble homepage is still awaiting content, but among the coming projects is a tutorial on editing and creating your own Tumblr theme, as well as others from Mozilla’s various Webmaker partners.

To help new users get their Thimble-created projects on the web Mozilla has also bundled a publishing function directly into the editor. Once you’ve got your Thimble page looking the way you’d like it, just hit the “Publish” button and Thimble will output and host your page, offering up a URL to share with friends and another to edit your page if there’s something you need to change.