Almost a year ago, I started working at 3D Hubs. Since I like domino-effects in
life-changing events I decided that besides finally entering start up life, I
was going to pursue two other goals: getting fit, as one should in the startup
world; and studying computer science more.
Full of confidence, I signed up for a year long gym membership and an at-home
bachelor course for computer science. I got to work and continued studying and
working out for… two weeks, maybe? Then, of course, I quit. The contracts
though, were quite strict: I was stuck to paying for a full year.
A few weeks ago I realised that I will soon be done paying off my self-imposed
fine, and I’ve been considering what I can do with this money. I could of
course buy more things with it, but that doesn’t seem quite like the wise,
adulty thing to do. And then the Mozilla rebranding happened, and suddenly
everyone was talking about Mozilla (and of course Firefox).
However you may feel about Firefox, it should be impossible to deny that
Mozilla is doing good work. As a (somewhat) large player in the browser market
they have a very effective vote in web standards, and they’re always pushing
for an open web. And now they’re finally putting more effort into improving
Firefox as well! I’m betting that Mozilla has a very good influence on the
Setting up monthly donations to Mozilla was a two minute task, and it doesn’t
take away from my monthly purchasing power. Very quickly after followed
Wikimedia—I was browsing Wikipedia for information on Mozilla. And now I think
I might be getting addicted to charity.
After Mozilla and Wikimedia followed Vluchtelingenwerk, a Dutch charity
supporting refugees. With conservative voices seemingly getting louder and
louder—especially now with Trump in office—helping organisations that support
refugees, minorities, and freedom (as in speech), seems increasingy important.
Giving small amounts of money each month to charitable organisations is a
really easy and incredibly effective way to do some good. So far, I’m donating
about €20 each month. Don’t be fooled by small amounts: every little bit always
helps, and you can always raise your gifts later.
To reallocate the money I was throwing away before, I want to continue setting
up periodical donations over the next few weeks. You can keep up with my list
of charities on my website.
If that list looks like bragging, it’s because I am. People need to be reminded
that charitable giving is normal. I am going to continue bragging, very
publicly, and I encourage you to do the same: spend your money on things you
believe in, and tell the world.
Commenting is a somewhat controversial topic, with opinions spread out over
mainly a single axis from those against and those in favour of commenting. The
one extreme says one shouldn’t have to comment at all since your code should be
readable enough to explain itself (I think of this as the arrogant approach),
while the other extreme claims that reading code is always bothersome and some
things will never be easily understandable so there should be plenty of
comments to explain it (in my mind, the hand-holding approach). I’d like to
propose a somewhat formal definition of the already existing middle ground: the
Documentation-Justification Method of Commenting Code.
The way I see it, there are two distinct commenting styles: describing the
usage of your code, which I’ll refer to as documentation, and elaborating on
your implementation, which I call justification. I’ll use these terms in my
explanation and reasoning below, but they can also be directly linked to more
practical conventions, which I’ll also expand on.
Documentation describes the usage of your code and should be very obvious to
any developer. Documentation tells the reader what they can expect from a
class, function or otherwise. It can define what something should be used as or
used for. It can also (and this may seem like a bit of a gray area here) expand
on the structure of your code: why did you create x as a class, why is this a
separate function. This is because it’s very important to understand the
structure of the project to fully understand the usage.
Justification tells the reader why you chose to implement something the way
you did. While your code should be readable enough to describe exactly what it
does step-by-step with a single read-through, it will never be able to explain
your reasons for choosing a certain implementation. There are many obvious
things choices that don’t need justification, and you shouldn’t justify those.
The usual example is
x++; // increment x by one, but there’s a lot more
complex code that doesn’t need commenting. It is of course up to the writer to
decide what code does and doesn’t need justification.
Justification is actually a little broader than that though: it may also be
used to explain a certain way to do something that is specific to your
framework that may not be obvious to the reader at first (but don’t repeat the
justification every time you use it). This one is a little further away from
the exact meaning of “justification”, but it should still be considered the
same commenting style since they are very closely related: they both comment on
a certain bit of code, instead of the structure. The term justification also
seems more appropriate and immediately clear about its primary purpose.
Most programming languages will offer you (at least) two methods to comment
your code: block comments, often
/* like so */, and line comments
// like this or
# this. Now that we have defined two separate commenting
styles, we can directly link them to comment methods. Block comments should be
used for documentation, whereas justification should use line comments.
This also more clearly links them to their meaning as described here:
documentation describe “building blocks” of your code and justification is more
closely related to the actual lines of code.
The DJ method and more importantly this write-down comes from my own struggle
with commenting methods, and my inability to pick what I should do. With a
somewhat formal definition, I can enforce (or at least encourage) a certain
commenting method in my own projects and those I set up in the workplace.
Separating commenting into two hopefully clear styles should make the method
simple enough to understand, and maybe simple enough for others to consider
Thanks for reading. If after reading it turns out you hate me and you want to
yell at me, I recommend sending me a tweet.
CSS is broken. It’s not possible to animate, in any way, an
Attempting to animate to or from
height: auto or
width: auto will yield
naught but disappointment, distress and questions: how do I fix it? Why doesn’t
this work? What’s going wrong here?