Coding Standards

1
Coding Standards
2
Coding Standards

• This is just how we, as humans, format our
  computer code.
• The computer does not care at all about this.
  How you format your code will not (directly)
  effect how your programs runs, at all.
• However, programming ( in practice ) is a team
  sports. Coding conventions can help the team
  work together better.
• So why are these important? Why might it be bad?

3
The Good

• Common standards a few good things happen
• Programmers can go into any code and figure out
  what's going on.
• New people can get up to speed quickly.
• People new to C are spared the need to develop
  a personal style and defend it to the death.
• People new to C are spared making the same
  mistakes over and over again.
• People tend to make fewer mistakes in consistent
  environments.

4
The Bad

• Youll hear lots of reasons why coding standards
  are bad / pointless. Some of the reasons are
  even almost valid. You may hear
• The standard is usually stupid because it was
  made by someone who doesn't understand C.
• The standard is usually stupid because it's not
  what I do.
• Standards reduce creativity.
• Standards are unnecessary as long as people are
  consistent.
• Standards enforce too much structure.
• People ignore standards anyway.

5
Project Engineering 101

• Software Engineering is an extraordinarily
  expensive undertaking.
• Because of this, it usually requires the code to
  stay around for a while - How long did Microsoft
  have to maintain/patch/(defend in court) Windows
  95?

6
Project Engineering 101

• Turnover rate is also very high for Software
  Engineers by some estimate as high as 30.
• So, even at a good company with a low turnover
  rate, say, 15, with 100 software engineers,
  thats 15 people that need to get up to speed on
  a project and 15 people that took all their
  knowledge about what they coded with them.

7
Project Engineering 101

• Also note that for the maintenance phase of a
  project can run 50-80 of the total engineering
  effort.
• So its very important for new programmers to be
  able to get up to speed in a relatively short
  amount of time.

8
What you can do

• There are a lot of things you can do, as a
  programmer, to make it easier for others to
  understand your code (we just saw why this is
  important.)
• Specifically, there are things you SHOULDNT DO.
  Although lots of programmers do them.

9
What you can do

• Im going to show you examples of these.
• Keep in mind, a lot of these examples are
  (purposely) a bit over the top.
• Im going to show you these examples from the
  point of view of someone whos TRYING to make his
  code unusable by anyone else.
• Dont let this distract you from the real point,
  these are things not to do and seeing people do
  this can make you understand why.

10
Single Letter/Very Short variable names

• By naming your variables a,b,c, etc., not only
  will no one know what they are, it also makes it
  impossible to search for them with a text editor.
• Two letter variable names are also almost as
  useless.

11
Naming

• In naming functions and variables, use abstract
  words like it, everything, data, handle, stuff,
  do, routine, perform and the digits e.g.
  routineX48, PerformDataFunction, DoIt,
  HandleStuff and do_args_method.

12
CapiTaliSaTion

• Randomly capitalize the first letter of a
  syllable in the middle of a word. For example
  ComputeRasterHistoGram().

13
Names from Mathematics

• Choose variable names that masquerade as
  mathematical operators, e.g.
• openParen ( slash asterix ) / equals

14
Bedazzling Names

• Choose variable names with irrelevant emotional
  connotation. e.g.
• Marypoppins ( superman starship ) / god
• This really confuses the reader because they
  have difficulty disassociating the emotional
  connotations of the words from the logic they're
  trying to think about.

15
Uppercase l looks a lot like the number 1

• Use lower case l to indicate long constants. e.g.
  10l is more likely to be mistaken for 101 that
  10L is.

16
Masquerading Techniques

• Include sections of code that is commented out
  but at first glance does not appear to be.
• for ( j0 jltarray_len j 8 )
• total arrayj0
• total arrayj1
• total arrayj2 / Main body of
• total arrayj3 loop is unrolled
• total arrayj4 for greater speed.
• total arrayj5 /
• total arrayj6
• Without the colour coding would you notice that
  three lines of code are commented out?

17
Red Herrings

• Pepper your code with variables that are never
  used and methods that are never called. This is
  most easily done by failing to remove code that
  is no longer used. You can save the code on
  grounds someday it may need to be revived. You
  get bonus points if these drone variables and
  methods have names similar to actual worker ones.
  The maintenance programmer will inevitably
  confuse the two. Changes made to drone code will
  happily compile, but have no effect.

18
Documentation

• Lie in the comments
• You don't have to actively lie, just fail to keep
  comments as up to date with the code.
• Document the obvious
• Pepper the code with comments like / add 1 to i
  / however, never document wooly stuff like the
  overall purpose of the program or function.

19
Documentation

• Document How Not Why
• Document only the details of what a program
  does, not what it is attempting to accomplish.
  That way, if there is a bug, the fixer will have
  no clue what the code should be doing.
• Avoid Documenting the "Obvious"
• If, for example, you were writing an airline
  reservation system, make sure there are at least
  25 places in the code that need to be modified if
  you were to add another airline. Never document
  where they are. People who come after you have no
  business modifying your code without thoroughly
  understanding every line of it.

20
Units of measure

• Never document the units of measure of any
  variable, input, output or parameter. e.g. feet,
  metres, cartons. This is not so important in bean
  counting, but it is very important in engineering
  work. As a corollary, never document the units of
  measure of any conversion constants, or how the
  values were derived. It is mild cheating, but
  very effective, to salt the code with some
  incorrect units of measure in the comments. If
  you are feeling particularly malicious, make up
  your own unit of measure name it after yourself
  or some obscure person and never define it. If
  somebody challenges you, tell them you did so
  that you could use integer rather than floating
  point arithmetic.

21
The Ugly?

• Were going to make up a coding standard for our
  class. Everyone in our class will use it. Itll
  be posted on the website.
• Its going to be fairly simple (read
  incomplete).
• The whole point of this is to get you thinking
  about structuring/commenting your programs not
  to rigidly enforce it.

22
So here it is

• 1) Each Source File should have a comment block
  at the top, with your name, the date, the program
  filename, and a short description in it.
• 2) Variables names should be self describing,
  exceptions being loop counters in for loops, etc.
• int myWeightInPounds int timeoutInMsec
• 3) Function names should also be self describing
• CheckForErrors() instead of ErrorCheck(),
  DumpDataToFile() instead of DataFile().
• 4) Use consistent case. camelCaseIsFine
• 5) Indentation always exactly 3 spaces, not
  tabs.
• 6) No magic numbers any number other than 0 or
  1 should have a constant defined for it.
  Example
• const int squareFeetInSquareYard 9

23
So here it is

• 7) Use spaces in all assignment statements, and
  always use brackets in control / repetition
  statements
• for ( int i 0 i lt someConstant i )
• //do something
• if ( a b )
• //do something
• This is sometimes referred to as One True
  Brace and it should almost always be used.
• 8) Use meaningful comments to describe complex
  situations, avoid unless comments.