Coding conventions and Culture

Rules to Live (and code) By

• Design from the top down, build from the bottom up

  • Design from the user's (the driver's) perspective: what will he/she see on the screen and do with their controls.

  • Write and test software starting with the lowest level (closest to the hardware) functions and then put them together into more complex functions.

• Never put cleverness before clarity

  • when choosing between a clever algorithm and one that will do the job and is easier to understand, use the latter.

• Understand ​coupling vs. cohesion deeply. These are the two most important concepts in software engineering, everything else is an attempt to increase cohesion and reduce coupling. Every block of code (class or function) should be a stand-alone black box with cleanly defined inputs and outputs. You should not need several files open to understand how one method works.

• Use meaningful names

  • Function/method names and parameters should convey what they do. For example:

    • move_arm(int direction);

  • Variable/data member names should convey what they store including units if appropriate. For example

    • int target_position_degrees;

• Comments should explain WHY. For example:

  • bad comment: int target_position_degrees; // target position in degrees

  • good comment: int target_position_degrees; // angle where arm should stop moving

• Tool (and language) wars are for noobs

• Being kind is better than being right

Coding Conventions

• Shift-Alt-F (auto-format)

• Make comments often about WHY, not what, you are doing

• Javadocs for EVERY SINGLE METHOD you have made

  • What it does

  • Why it is happening

  • Define each parameter

• document your code thoroughly so someone else can read and understand it. Good code contains at least as many lines of good comments as of executable code...no matter how readable you think your code is.

• clean up your code before you check it in. Don't leave gobs of test code and debug print statements in your code. When you make your code available to others, that should all be removed and the code should be clean and readable.

Software Culture

• Read ​Joel on Software

• Appreciate ​programmer humor