WORK IN PROGRESS

I have been working as a software engineer for ten years now. Whenever I thought I have seen it all, I have been shown worse. Violations of rules and best practices so simple and base that they are written in every book... except they are not. So I started to assemble a list of these rules and best practices for future reference.

The "you" addressed in this text is in a management position.

Borrowed Time

Everything will come back to you threefold.

Any of the rules quoted below is essential for effective software engineering.

If you believe you can skip one or two of them "because we don't have the time" or "to get it done quickly", you are living on borrowed time. In the end, skipping any of the rules will cost you dearly. Not only will you lose time and money beyond what you initially saved, you will also pay in customer and employee satisfaction.

Rules do not enforce themselves.

Just writing down a number of rules does not change anything. Make sure every new developer in your department is told these rules. Make sure the rules are understood and accepted, perhaps by drawing in some "old hands" who can tell of the mayhem that ensues if they are not.

Then make sure that adherence to these rules is checked for. The most effective way to do this is Peer Review. Here, it is very important that such reviews are not considered as some kind of exam by anyone involved ("who is writing the best code in the department"). They are a means to check for and improve the quality of software. No more, no less.

Peer Review

Unless you are already on a "four-eyes" policy, you should hold  peer reviews at regular intervals. If you just skipped over that link, go back and read it! A carelessly done peer review can damage your team'' Most importantly, it should be clear to all parties involved that a peer review is never to be meant as some kind of exam. Its sole purpose is to improve the overall quality of work.

Bus Factor, pt. 1

Always assume you won't return to work tomorrow. Even if you are not run over by a bus, hit by a meteor or abducted by aliens, you might win the lottery big time, become ill, lose all memories, or otherwise become lost to the project, temporarily or permanently. Keep your workspace organized, check in your source at the end of the day, update the tickets you are working on before you shut down your workstation for the evening. Anyone should be able to take over what you were working upon on a one-day notice.

A common manager misconception is that this "anyone" would be able to work with the same efficiency on a one-day notice. That, of course, is utter nonsense. Keeping everything tidy, checked in and documented only means this "anyone" does not have to pick up lots of lose threads.

Reproducability

This is actually the most important thing in software engineering. Imagine a desaster just wiped out all your production servers, including all backups. Would you be able to take new hardware, and set up just the same software environment as before?

Comments

Anybody who claims that source comments are unnecessary for any reason should either:

• agree to the policy that, yes, in this project, everybody (including him) does write source comments, or
• leave the project.

Fallacy #1: The Truth is in the Source

Source only tells you the how. Most of the time, developers will only skim the code trying to figure out what it does. This is very much facilitated by function and block comments.

Another point is that your code might not actually do what you intended it to do. Unless you documented your intention somewhere close by - e.g. a source comment - it is hard to tell.

Source Control

Documentation

Review

Technical

Do not use LD_LIBRARY_PATH.