Sunday, June 14, 2015

How to code: lesson 27

I was reading some code on the Internet today and came across this:

The thing to notice is the hang & symbols in front of the variables, instead of just making things line up. It's a stylistic quirk of the author of this code. It's a good lesson on what not to do.

There is only one important style rule and it is this: make your code look like everyone else's. The question isn't whether it's good or bad, only that it's unusual. Yes, this quick is relatively insignificant, but I point it out is that you should not be tempted, even on the smallest of things.

You see this with the evolution of programmers. In the beginning, their code is quirky as hell. Over time, as they they are exposed to more and more source by others, they start to see how these quirks are irritating, and stop doing them in their own code. The style becomes blander and blander -- but at the same time, the greatness of their construction of the code starts to shine.

When you start writing great code, you'll eventually have to break this rule and do something big and strange. For example, I do this with my "state-machine parsers". It's a programming pattern unfamiliar to most programmers, yet I have to do it because the scalability and performance are huge. Save your quirks for the big things -- exorcise them in the small things.

By the way, I meant this as the only important style rule. It really is. A lot of companies spend a great deal of time, and politically gnashing of teeth among developers, in order to draft style guidelines. This is garbage -- it truly does not matter where you put braces, for example. Experienced coders have to be accustomed to reading various styles anyway. Here's what you should do. Start a program asking anybody who is interested to come in after work in order to draft a new set of style guidelines. Fire everyone who shows up -- they are political animals who are likely deadweight anyway. Then just pick a style guideline at random, like the Linux kernel style doc or the WebKit style. Or, pick no style at all -- your project is going to pull in a lot of open-source with varying styles anyway, so it's pointless trying to make it conform.

BTW, when I invested all my money in a startup consisting of a team of programmers, when my entire life's saving depending on quality code being produced, I imposed this guideline on the team: stop with the nonsense, make it look normal. Each programmer had different styles, but yet the code produced was high quality anyway. It really can work.


David Wong said...

> A lot of companies spend a great deal of time, and politically gnashing of teeth among developers, in order to draft style guidelines.

What they should do is re-use a famous/official one.

One thing more irritating than little quirks is inconsistent code-style in the same project

Thomas Seeling said...

I can't see what exactly is wrong with that quoted style. The programmer wants to point out (mostly for himself I guess) that some parameters are pointer values (yes I see the pun) which can be expected to be changed upon return from the call. That's a perfect reasoning.

Later on you say "just pick one by random" - that's exactly countering your prior criticism.

Robert Graham said...

Pick one POPULAR one at random, that everyone knows, some not something quirky that nobody has seen before.