Common Sense 4 Common People

Tips on writing C macros

Macros in C/C++ is an extremely powerful feature, basically one I can't live without. The use of macros has been widely debated and mostly they are labeled as 'evil', as a no-no. This is the usual moral dillema that shows up whenever we have something with significant power in our hands: Anything that is powerful enough can be misused one way or the other. Should we then allow the usage of the powerful tool or ban it altogether so as to prevent its misuse (intentional or unintentional)?

The code is THE documentation

Yeah sure... Sleep tight and noone is gonna rock your boat, at least while you are sleeping in it.

This is a very luring statement. The reason it is so luring is that it is so obviously true. Or is it not? Doesn't the program do exactly what the code tells it too? So the code is THE one and only always up-to-date documentation of any program. Right?

It is so convincing that you just can't resist falling for it, especially when faced with an aficionado that passionately claims that she doesn't need to write comments as "extra" documentation, because the code is THE documentation, and since she obviously writes top quality code, comments are simply redundant. A waste of screen estate more or less. Useless clutter around the actual documentation.

Sorry to break the news boys and girls... The reality is somehow different.

The code is the imperfect translation into a programming language of the programmer’s imperfect understanding about what the program should do.

You can figure out the rest. The code is THE documentation of the programmer's imperfect language translation of an imperfect understanding. It documents how the programmer failed to code properly what he failed to understand properly.

Anyone still battling on the issue of whether the code is THE documentation and whether comments (in any form) are needed or not, most likely hasn’t worked on a big project (300+KLOC) long enough (5+ years) to figure things out for him/herself.

Life is so sweet when 90% of the time you fool around your own code. Everything is so simple, because everything is in your head. However once you start spending 50% of your time on pieces of code that other people wrote, pieces of code you have NEVER seen before, or pieces of your own code that you wrote 4 years ago and haven't glanced at since, then life is not as sweet.

When you read code you are not familiar with, then you are doing the reverse translation, from imperfect programming language to imperfect understanding about the program's intentions. This is tough. Some may be better at it than others, but trust me... without good comments it can be much more painful and error prone than it has to.

So please, make others' lives easier. Let them cherish your memory after you are gone and enjoy fixing the bugs in your code. Because you WILL be gone some day and your code WILL still have bugs that need fixing.

Enjoy,
Dimitris Staikos

Psychology is a science, NOT just Common Sense

This is an excerpt from an excellent book that I am currently reading:

It's no surprise that people who are faced with choices about how to influence others will often base their decisions on thinking that's grounded in fields such as economics, political science and public policy. What's puzzling, however, is how frequently decision-makers fail to consider established theories and practices in psychology.

One explanation is that, in contrast to how they regard the fields of economics, political science and public policy, which requires learning from outsiders to achieve even a minimal level of competence, people believe they already possess an intuitive understanding of psychological principles simply by virtue of living life and interacting with others. This overconfidence leads people to miss golden opportunities.

It is really sad to see otherwise smart people feverously deny any chance to improve their soft-skills, to attend seminars about human behaviour, influence, negotiations, etc. Their thinking appears to be something of the sort "Hey dude, can't you see what great a manager I am? How did I get here? Because I am smart and because I am good, really good. I need no silly seminars to tell me how to do my job!".

As the book says, they believe they already have ALL the skills they need, plus they believe (in their hearts) that they do a damned good job, almost perfect. They think that psychology is common sense; if you are smart enough you can figure it out by yourself. But it's not that way. Psychology is a real science and you definitely cannot figure it out. Just read a couple of good texts and after your jaw drops to the floor for a couple dozens of times you will know that you could never have figured it out.

Needless to say, the competition will sooner or later do their part of the studying and inevitably they will outrun these managers and their companies. It's as certain as death and taxes.

Have fun,

Dimitris Staikos