Category Archives: Uncategorized

‘Self-Documenting Code’ is Not Enough: Why Code Needs Inline Comments

But don’t waste your time documenting what you did; document what you thought.

Coding is hard. And the thing you spend the most time doing isn’t typing: you spend the most time reading and trying to understand code. This applies not only to other people’s code, but also to your own, more than 10 minutes after you wrote it.

This is why documenting your code is so critical, as well as taking the time to write clean, readable code. Clear code is far better than clever code. (In fact, I might go so far as to say that clever code is usually a premature and self-justifying optimization, unless accompanied by myriad apologies and disclaimers.)

But, somewhere along the way, the virtue of clarity somehow becomes controversial. Some of us are sailors on the Aegean, and hear the siren song of ‘self-documenting code’ calling us to dash ourselves against the rocks of piety and self-delusion.

Today, I spoke with a wonderful mid-level engineer about some code that lacked any inline comments whatsoever. (He hadn’t written it.) He kind of agreed that was an issue… but then also disagreed, and explained why. A little while ago, a more senior engineer (herself no dummy) had told him comments were bad, and distracting… that all code should be self-documenting. Which… sounded right. Who could disagree with the idea of naming things well? Of making code readable? So, he stopped writing comments.

First, let’s just acknowledge: there are a LOT of useless comments out there. If the CSS selector is ::-webkit-scrollbar, and then it has a rule that says background: transparent, I do NOT need an annotation next to that rule which that combines 2 of those obvious keywords with an action verb to tell me it will: /* make scrollbar transparent */. I mean… I’m grateful someone’s commenting, and I’m not saying they’re a bad person who should burn in hell, but just… they should save their effort for something actually useful, eh?

Further, there’s a particular affliction of certain IDE’s and other automated tools, whereby they produce metric tons of boilerplate comments that nobody ever reads, and which in fact reduce the overall signal-to-noise ratio. This is also bad.

But don’t throw the baby out with the bath water. The problem is not the institution of inline documentation of code, but its misuse. Just as statistics themselves are not dishonest (a la: “lies, damn lies, and statistics!”), inline comments are not a bad thing… but they are sometimes abused to bad effect.

Further, writing code that is as self-documenting ** as possible ** is an unmitigatedly Good Thing. Variable, class and function names should indeed be rich and explanatory! Comments that re-explain what’s objectively obvious are noise without benefit. There are only two hard things in CS, etc., etc.

But not all code can self-document, and not all things can be present in code. In particular, code is only your implementation of an idea, but the most important things to document are those things which are not present:

  • The intent/purpose of code
  • Whatever’s hiding on the other side of an interface (call and return signatures, let alone behavior)
  • Any alternative implementation paths which didn’t work for some reason: these are landmines to warn your successors away from

At a minimum, inline documentation should address those things: it should explain that which your code cannot, at least not without successors needing to dive deep into reading the source of all the things on the other side of an interface. And after all, isn’t the point of documentation to save time? To avoid reinventing wheels, to avoid breaking useful abstractions?

But there’s also another point to documentation, and it’s the same point often raised about testing: writing about your code forces you to think it through, to understand it yourself better than you would if you didn’t examine and define your assumptions. And that kind of documentation interlocks with your testing: when you write down the arguments you expect your code to accept, and the responses it should provide, you give yourself a list of targets to hit, and you remind yourself of all the ways you could blow it.

Sometimes your user story defines those targets for you… although unless you provide a link to the story, that doesn’t help anyone who comes after you. And other times, as when you write a helper utility, or some other piece of behind-the-scenes plumbing, not even JIRA can tell anyone what you were trying to do. It’s up to you to explain that, and up to you to force yourself to be clear and explicit about your intentions… so that the resulting quality of your implementation can document itself.

Moreover, in stating your intentions and assumptions… you allow your successors to determine where your code failed to live up to them. But if you state your assumption (for instance that you expect only numbers as arguments to a function), you let me help find what you overlooked (that Javascript and other dynamically-typed languages can easily coerce non-numeric values in ways you didn’t anticipate).

Last, half the point of code review is for the reviewer to test whether code is clear and understandable without requiring an exorbitant amount of context, and without requiring the reviewer to go read a bunch of source somewhere else:

Reduce WTF/m. Comment your code, not by restating what’s obvious, but by exposing what’s not.

Cleanliness is next to godliness, in a dev’s consoles

(This piece is based on my current Javascript development stack, but the principle applies almost anywhere.)

So, the whole premise of coding in a complex project, with an environment that is itself likely quite complex, is to be able to conserve your attention. To focus it like a laser on the Things That Matter, and to notice those things, when they appear. But that becomes impossible if you’re surrounded by noise that drowns out the Things That Matter.

Consider your browser’s Javascript console, which you ideally have open all the time while you develop. Also, chances are you’ve got a terminal/TTY window open as well, running your servers/builds while you work. Consider that, too.

If there are two unusual things in there, you’re likely to notice both of them. And you can do something about them. But if there are 107, you’re likely not to. So,


`console.log()` statements pile up like the fine snow that begins a blizzard. At first, you barely notice the light layer of fuzz, and everything feels cozy and lived in. And then suddenly you can’t see your mailbox anymore and you’re wondering whether your kids and dog made it inside alive. It’s pretty much an exponential curve.

Or, call it the ‘broken windows theory of console statements’: it only takes the first couple of them ruining the place and suddenly it’s urban blight that nobody will bother to maintain, or could if they wanted to. And instead of just fixing the first few broken windows when they happened, it gets out of control, and you find yourself needing a wholesale urban restoration initiative. People lock their doors and roll up their windows when they drive by your console.  You don’t want that.

Further, there’s even some pretty heavy-duty research about the effect of messy workspaces on human productivity. One methodology that describes this is the 5S approach to manufacturing. So… 5S your consoles.

So, it’s OK if you scatter some `log()` statements around while you’re working. Heck, even if you commit them. But clean them up before you push, or otherwise make your work permanent. Even if it’s a repo of one, it’ll quickly become a dark alley that even you don’t want to travel down after dark. And if it’s a repo you share with others, it gets out of control much more quickly.

Make use of something like ESLint to warn you about them. You can run it as part of your PR sequence, or during your local build. But one way or another, you want something to nag you annoyingly to get rid of them before you push and inflict them on everybody else on your team. Or get used to them yourself. Because if nothing’s nagging you to fix them, you’ll be buried under them before you know it.


The problem with letting your cruft pile up is that you stop noticing things. Nothing sticks out any more. So, even a really important error that actually explains why everything just broke – or will, soon – is just another signal buried in the noise.

All that noise makes you numb. It’s sensory overload. You desperately need to cut down on the noise, so unexpected errors grab your attention when they happen.

And when they do happen, you need to jump on them. Even if you just file an Issue for now while you wrap up something else, it needs to be remarked upon and tracked down, until you can at least understand why it’s happening. And if you’re OK with the reason once you understand it, then feel free to leave it there.

For a little while. But once you have more than one of those, it counts as cruft and noise that drowns out the signals you need to see. <GOTO: PREMISE #1> And thus you need to find a way to get rid of it.

But if you don’t understand it, and if the existence of that signal doesn’t bother you… you’re a problem. When I interview people whose sample code produces random errors they don’t understand, they don’t get hired. I need you to need to understand what’s causing that error. I don’t actually care, under the right circumstances, if you fixed it. But if you didn’t care enough to even understand it, or try, or even to ask about it, you’re toast.

And if you’re working on a project with me and you do that? If we’ve both – and perhaps our colleagues, too – poured weeks or months of blood and sweat into something, and it doesn’t bother you that you created something that’s pumping out errors from our lovely code… then we have a problem. You’re hurting the project. You’re making me sad. Please, please, don’t make me sad. Figure out what’s causing the error.

Or, use this principle: Say No! Then Go! And tell someone you trust! Seriously: it’s OK if you really don’t understand an error yourself. But you gotta’ ask for help.

Because accepting bad things like that without a fight, and letting it ride indefinitely is… well, it’s a lot like having some big oozing sore on your forehead that you haven’t bothered to wonder about or treat. People won’t like you. The other kids at school will make fun. Parts of you will fall off and die. That sort of thing. Don’t recommend it.

Conclusion: It’s Not Just Aesthetics, It’s Effectiveness

To conserve your attention, you need to be able to focus on what matters. That means cutting down on useless signals that try to distract you, and make it harder for you to do your work. 5S up your consoles: you’ll be glad you did.

And, then once you have a clean console and can see what’s right in front of your eyes: don’t ignore it. Whatever is still left is there for a reason. Understand it, or your missing the point, and making it harder to keep a clean workspace.

JSChannel 2015 Video, plus ReactConf Video, Etc.

Anyone who missed JSChannel 2015, or who just wants to re-view it, can catch the video on YouTube! See Day 1, Day 2. (FWIW, my React/Flux Workshop begins at about 3:47:25, but avoid it if you can’t handle seeing a couple cringe-worthy one-time compilation failures I still can’t explain. 🙂

And, since I was talking about React that day, it’s also worth checking out the video from React.js Conf 2015. Plus, there’s the React-Native talk from F8. And React-Europe.

Workshop Slides from JSChannel Conference Bangalore 2015: “React & Flux”

Thanks to the JSChannel team for having me! Slides are available below, and the associated GitHub repos are here: jschannel-react-demos & jschannel-flux-demos

Continue reading

Why You Should Never Again do a Scrollable List with ng-repeat

Anybody who’s ever done a long, scrollable list of items in a web interface knows that this can absolutely kill performance of the whole page, let alone the scrolling itself. People blame tools like Angular’s `ng-repeat` for performance problems, but the problem isn’t the tools: it’s just that they make it so damn easy to do things… you should not do. Performance of your page is inversely proportional to the DOM count, and a massive list of items may square or cube the number of elements in the interface.

We do all kinds of workarounds to deal with this: pagination, “infinite” scroll (which is badly misnamed, but I digress), etc. But there’s now a much easier, cleaner way to have as many items as you want, without penalty: don’t create elements for all the items in your list. Just however many will fit in the window, plus two or so. And recycle them into whichever position your user is scrolling in. (It’s Green!™) Conceptually, it’s very simple. Implementation-wise… most of us would like someone else to do the heavy lifting.

I first saw this approach mentioned in the Sencha Labs post about their “FastBook” experiment, in which they called it an ‘Infinite List’. Thereafter, I was surprised I hadn’t seen that approach adopted elsewhere in JavascriptLand soon after, and am sad I never got around to trying to build one myself. (Maybe someone else did. I missed it. Please share other implementations in the comments!)

But now, the Ionic UI framework has an Angular directive for this, which they call the `collection-repeat`. You. Must. Use. This. In Ionic, out of Ionic, whatever. And hack it, port it to other frameworks, tweak it, extend it, and just generally make sure that you never do long lists with naiive ng-repeat… ever again.

Tagged , , , , ,

About Using CSS Floats for Primary Layout: Stop It Already

The piece of my CSSConf Asia talk that generated the most heat in the Twittersphere was the following claim:

Floats were invented for one reason and one reason alone: to allow text to wrap around an image. They were not intended to do what we do with them. I know this hurts to hear it: but Floats are the table-based layout of our time. Unless you have to support IE6, stop using them, except in very specific, very limited situations.

So, let’s just add some quick clarity to that, as conference talks need to be more concise than is ideal: floats are cool for tactical uses, and are downright invaluable if you’re supporting old IE and can’t use display:inline-block as yet, let alone Flexbox. Even with inline-block available to you, there are still places where floats are super-handy, like kicking a single element in a toolbar off to the right, or when you really do want to wrap your inline text around an image. Continue reading

Tagged , , , , ,

My CSSConf Asia Video is Now on YouTube: “Scalable CSS”

Woops! I’ve just realized I never posted my slides, either. Here they are:

Tagged , ,

Why I’ve stopped doing single-line-define-and-assign on Angular $scope

I’ve been using Angular for all of my rapid-prototyping work for almost three years now. I’m very comfortable with the Angular idiom. But there’s one piece of it that I’ve entirely abandoned as bad hygiene and broken functionality (at least when mixed with ‘function statements’): the ‘single-line-define-and-assign’ pattern for variables and functions we want to expose via Angular’s $scope:

$scope.myVar = 12345;
$scope.myFunction = function () {/* do stuff */};

Instead, I do it like this:

var myVar = 12345;
function myFunction() {
  /* do stuff */

$scope.myVar = myVar;
$scope.myFunction = myFunction;

<screaming ensues> I know, I know. “Ur doin’ it wrong!” But read on, and scream after.

Continue reading

Tagged , ,

Software, Fear, Neuroscience and Agile Person-Hood

  • The same ‘agile’ principles that make your project team more effective as a whole will make you a better teammate as an individual.
  • Agile principles are about letting go of fear and control, and optimizing for transparency and trust.
  • This is true enough in good times, but it’s *especially* true in harder times.
  • Your own limits and challenges in life are no different than the limits and risks that the team encounters. Be as transparent about yourself to your team as your team is to the project’s stakeholders.
  • Embrace the inevitability of risk, and activate your brain’s optimism module.
  • Renovating a house while you build software is going to provide you with far too many opportunities for recursive learnings about agile project management from all possible perspectives.

Fairly recently, I failed. Fortunately, it wasn’t a messy, catastrophic, collective failure of an entire project, or blowing through $200 million of my investors’ money, then selling off the company for scrap. Rather, my project team succeeded in doing what it set out to do, in spite of the fact that I failed to be a good teammate for them. We didn’t fail together; I failed them.

The proximate cause wasn’t hard to identify: I was totally, completely overwhelmed. Tons of work, and tons going on at home. (Among other things, we gut-renovated an apartment, which is pretty much a full time job, even when you’re paying other people to do the heavy lifting. Cancel all your other commitments if you should ever be so foolishly inclined.) And then the previous, particularly important project suffered spectacular scope-creep and nearly went off the rails, resulting in a bunch of 80-hour weeks and working through most of Christmas vacation.

And so I showed up to this specific project with my gas tank pretty empty. No doubt about it. But that’s not *why* I was a bad teammate. It’s just the set of stressors that exposed some underlying weaknesses: habits that were flawed but manageable under normal circumstances, but which became totally non-viable when things hit the fan.

The thing is, you can be overwhelmed and still be a great member of your team, albeit with a decreased output, or with a need to rely more heavily on other people, or without your normally sunny disposition being quite as sunny. But you have to make the right choices and have the right habits in order to do that. That’s what I’m here to talk about. Continue reading

Find the Comments for Bootstrap CSS: ‘Hiding’ in the Less/Sass

Surprisingly, for such a mature and robust open-source product, the basic bootstrap.css file most people download is almost entirely uncommented. The only comment characters you’ll find are the credits/attributions, an old IE 8-9 hack, and at the very bottom, the sourceMappingURL. And that’s in the unminified version of the file.

This comes from a very fundamental bias on the part of the authors: they’d apparently really, really, really like you to use Bootstrap with Less or Sass. The source files for Bootstrap CSS are Less files, and have to be compiled into the basic .css or .min.css download versions. In the source, you’ve got all kinds of handy inline comments. And I have to admit, it’s an awfully good idea to use a preprocessor with Bootstrap. There’s a whole additional layer of abstraction and customizability that opens up to you when you use one: whole files full of handy variables and mixins, and the ability to toggle CSS modules on and off at-will, by simply commenting out an @import statement from the bootstrap.scss/bootstrap.less file. (Which, indeed, is nothing but a long list of categorized @import statements.) Leaving aside the other virtues of CSS preprocessors, using one with Bootstrap suddenly switches it from being monolithic, over-opinionated, and fit only for rapid-prototyping, to something a real CSS pro could reasonably take home to Mom. Particularly if you’re on Bootstrap only because your team is used to it and doesn’t want to switch to something a little more pro-grade (<cough>… Foundation… <cough>), at least using a preprocessor is the way to go.

That said, I think a good chunk of the Bootstrap community never has used it with a preprocessor, and won’t do so soon. Those folks are missing out in a major way. With decent comments, you can easily toggle the modules on/off by just commenting them in/out, and you can better understand what Bootstrap is doing for you. (Largely so you can get it to STOP doing the things that are bugging you.) For those folks, I’ve got a recommendation.

Download either the Sass or Less version of the source. Even if you’re not going to start using Sass or Less, you can crack open the source files and see all the helpful comments there. Starting from the bootstrap.scss or bootstrap.less files, you can see all the individual modules that are @import-ed, and the order in which they contribute to the final compiled .css file. Then, diving into the individual modules, you’ll find comments that explain what most of the classes do and why they do it. And, using the module files as a reference for start and end points, you can more easily strip out the modules that contain classes that are just cruft.

Bonus recommendation: tell the dev team (politely and helpfully!) that you’d like to see the comments make their way into the un-minified .css, perhaps with an indicator for where each module begins and ends.

Tagged , , , , ,