“Good Code Documents Itself” And Other Hilarious Jokes You Shouldn’t Tell Yourself

Code documentation — is there anything more exciting than spending your time writing extensive comments? If I had to guess, your answer is probably somewhere along the lines of “uhm, yes, everything is more exciting than that”. Plus, requesting to document your code is almost like an insult to your well thought out design, this beautiful creation you implemented so carefully that it just has to be obvious what is happening. Writing about it is just redundant, the code is all you need.

As a result, no matter if it’s some open source side project or professional software development, code documentation usually comes in two flavors: absent and useless. The dislike for documenting ones code seems universal among programmers of any field or language, no matter where in the world they are. And it’s understandable, after all, you’re in it for the coding, implementing all the fun stuff. If you wanted to tell stories, you would have chosen a different path in life.

This reluctance has even formed whole new paradigms and philosophies claiming how comments are actually harmful, and anyone trying to weasel their way out of it can now happily rehash all those claims. But, to exaggerate a bit, we’re essentially villainizing information this way. While it is true that comments can be counterproductive, it’s more the fundamental attitude towards them that causes the harm here.

In the end, code documentation is a lot like error handling, we are told early on how it’s important and necessary, but we fail to understand why and instead grow to resent doing it again for that same old teacher, supervisor, or annoying teammate. But just like error handling, we are the ones who can actually benefit the most from it — if done right. But in order to do it right, we need to face some harsh truths and start admitting that there is no such thing as self-documenting code, and maybe we simply don’t understand what we’re actually doing if we can’t manage to write a few words about it.

So let’s burst some bubbles!

Continue reading ““Good Code Documents Itself” And Other Hilarious Jokes You Shouldn’t Tell Yourself”

Path to Craftsmanship: The Art of Being Wrong

Every technical person knows, unlike artists and politicians, that they can be provably wrong; at least to a degree. Math tells the truth. Coupled with this knowledge is an ego which is often entirely based on our output. If our mechanism works, we feel good because we are provably good.

A disclaimer.
It didn’t stop Scott Adams from writing four books full of it and it won’t stop me.
from Dilbert: Advice

Unfortunately, unlike the robots we build or the simple minds we spin out of code, we are still human at the end of the day. When we feel the sting of being wrong we often respond poorly. Some of us slip into depression, claiming it all and dredging up a few other mistakes from our past along for the ride. Some of us explode into prideful rages, dropping our metaphorical shorts to show that this one fault is no fault at all compared to a history of personal majesty. Others become sullen and inward. Others ignore it all together. Others yet strike out at those around them leaving unpleasant barbs. The variations are endless, but I do think there is an ideal to be reached.

Despite the risk that the nature of the things I’ve learned will reveal exactly what kind of arrogant sod I am, I’ll give it a go anyway. I’ve made many mistakes, and I have many more to make, but these are some of the things I’ve learned. I’ve learned them all in technical fields, so I’m not sure how broadly the advice applies, but luckily this is Hackaday.

Continue reading “Path to Craftsmanship: The Art of Being Wrong”

Path to Craftsmanship: Safety, Cleanliness, and Documentation as Habits

When I started boxing classes I was told, at my level, I could do just as much good for my form by doing core exercises such as crunches, running, push-ups, and pull-ups for a month as I could by doing the class. I consder habits like safety, cleanliness, and documentation to be habits that influence the quality of hacks much the same way. They’re not really related, and the work can get done without them, but their implementation alone improves the quality of everything you do at the workbench.

The best mechanic I’ve ever met had a well-organized shop. All of his employees wore nitrile gloves when they worked on engines to protect their hands from the chemicals inside. They used ear protection and safety glasses. His rates were low, and the car was always repaired fast. I never had to go back for the same repair twice. He knew exactly what repairs were done, and even kept the parts removed from my vehicle to show me if I desired. I got some of the most fantastic explanations of why parts failed from him. Two blocks down the street was a shop which was unorganized and had double rates. The employees were always sitting on the waiting chairs in the lounge. It took one trip there to never return.

Continue reading “Path to Craftsmanship: Safety, Cleanliness, and Documentation as Habits”