Style Guide

From Thalesians
Jump to: navigation, search

Contents

Philosophy

The choice between doing and not doing is often disguised as the choice between doing and doing perfectly. We don't want to wait until we are ready for perfection for fear of missing the train. We do the best we can now.

In particular, we don't wait until we know a technology inside out before we start using it. We dive into it and learn as we go, correcting our imperfections along the way.

We don't wait until we are fully equipped to attack a mathematical problem. We approach it with a clear and open mind and apply the familiar techniques first. Then, if and only if it becomes obvious that something is lacking, we pause and learn.

We don't wait until we have gathered all imaginable requirements before we start a project. We start the project relying on intuition and busily gather requirements as we go. Knowledge and understanding will eventually displace intuition, though never completely.

Thalesian Tenets

  1. No knowledge is trivial knowledge. We accummulate knowledge. Chances are, this knowledge will seem trivial to some. However, we do not believe that knowledge can be qualified as trivial. Therefore if you have something to say, please say it without fear.

English Language

Introduction

We believe that language should be used to express ideas as correctly and accurately as possible while minimising the number of words used.

We are not so worried about the length of words and sophistication of the language that we use, as we assume that we are talking to educated public. But we shall strive to avoid complexity where it is unnecessary.

Corporate language can be brief and precise as exemplified by some trade term sheets. It can also be wordy and obscure as illustrated by sales and recruitment pitches. Words such as "leverage" and "synergy" should only be used where they have a clear and unambiguous meaning. In most cases they are best avoided.

Don Knuth: email versus e-mail

We cite Don Knuth:

Newly coined nonce words of English are often spelled with a hyphen, but the hyphen disappears when the words become widely used. For example, people used to write "non-zero" and "soft-ware" instead of "nonzero" and "software"; the same trend has occurred for hundreds of other words. Thus it's high time for everybody to stop using the archaic spelling "e-mail". Think of how many keystrokes you will save in your lifetime if you stop now! The form "email" has been well established in England for several years, so I am amazed to see Americans being overly conservative in this regard. (Of course, "email" has been a familiar word in France, Germany, and the Netherlands much longer than in England — but for an entirely different reason.)

Programming

Apologetics

We can hardly be termed control freaks, but we like coding standards.

Why have coding standards?

According to Sun (http://java.sun.com/docs/codeconv/), "Code conventions are important to programmers for a number of reasons:

  • 80% of the lifetime cost of a piece of software goes to maintenance.
  • Hardly any software is maintained for its whole life by the original author.
  • Code conventions improve the readability of the software, allowing engineers to understand new code more quickly and thoroughly."

General

  • Avoid tabs. Tabs cause a lot of problems in cross-platform development. For example, should we display each tab as 4 spaces or 8? There is no authoritative standard in this field. Different operating systems, editors, etc. treat tabs differently. You may not even be aware of the problem. Your code may look perfectly fine in your editors while appearing illegible in that of your colleague's. Therefore we avoid tabs and always use spaces in their place. Replace each tab with 4 spaces.

Eclipse IDE Settings

  • Text Editors. In Window > Preferences select General > Editors > Text Editors:
    • Set Displayed tab width to 4.
    • Enable Insert spaces for tabs.
    • Enable Show print margin.
    • Set Print margin column to 75.
    • Enable Show line numbers.

C++

Prerequisites

  • Before contributing to our code, everyone should read and understand the latest edition of Effective C++ by Scott Meyers.

Java

Prerequisites

  • Before contributing to our code, everyone should read and understand the latest edition (currently it's second) of Effective Java by Joshua Bloch.

Coding Standards

We use the current (as of 26 January, 2009) version of the Code Conventions for the Java Programming Language modified to fit our philosophy better. Details to follow.

Coding Standards — under construction.

Personal tools