Difference between revisions of "Coding Style Guidelines"

Revision as of 21:43, 25 June 2013

In general, if you have a legacy project, you should follow the same style guidelines as are already in that project. Unless you want to reformat and fix the ENTIRE project. Consult with me before doing this, but it is probably a waste of time.

Editor

You should be using emacs or vim. Do not use anything else. There is a reason that these editors have been around for 30+ years. They make you productive and are available on every system.

Learn to use your editor well by completing online tutorials. Starting learning a new "tip" every week. If a task requires repeatedly pressing a key, there is likely a better way to do it. If it is very useful, share it with the group via the email list!

Line Wrapping

Never have a line longer that 100 characters. Both vim and emacs have methods to automatically line wrap text -- use them. In programs, you should rewrite the code (see later section on Clean Code).

Indentation

You should use consistent indentation. Follow the conventions used in the existing code. Do not start your own convention that is inconsistent with the remaining code base.

Variable Names

You should use consistent variable names. Camel case (camelCaseIsLikeThis) or underscores (underscores_is_like_this) are the two preferred option. Do not start your own convention that is inconsistent with the remaining code base.

Revision Control

All code should exist in a revision control system. It can be SVN or Git or whatever your choice. I recommend the group repository.

You should not commit any temporary files into a repository. If it is a temporary or generated file, it will change automatically every time you compile. This then causes unnecessary differences in the repository and creates bloat.

Do not check in non-working code. Before you check in, you should verify that any unit tests pass and that all new files are added. Ommitting a file will break the code for everyone else! Use svn status to check if you have any files not added or are still locally modified.

Clean Code

These items are initially based off the book: "Clean Code" Publisher: Prentice Hall By: Robert C. Martin ISBN: 978-0-13-235088-4 Year: 2008 If you think that one of these summaries is unclear, please fix it.

Chapter 1: Leave the code (in the repository) cleaner than you left it. Never leave temporary code, make other code better than it was before.

Chapter 2: Use meaningful names for variables, functions, classes, etc. If you cannot tell what it is from the name (without comments), it should be renamed. Make it long enough to express, but keep it short for density. Easy searchable and pronounceable names are best.

Chapter 3 Keep functions small. No more than 3 parameters (or make a structure argument. Only have one return variable which is not a parameter. Functions should not have side effects that are not clear. Functions should do one thing well.

Chapter 4 Best comment is no comment. Comments should only be added if a design choice needs to be documented or an odd behavior is evident. Do NOT leave commented out code.

Chapter 5 Vertical one: downwards rule. High level to low. Stay close if conceptual affinity Horizontal one: enforced by python.

Chapter 6 Object expose behavior Data(class) expose obviously data similar to the idea of Separate the data path and control path

Chapter 7 concept of exception do not exist in python. However, the code should provide helpful information than just producing error message. Null information should not be produced or passed, error class is better.

Bin Wu its called checked exception in the book(Page 106, Use Unchecked Exceptions ,Paragraph 2). I am still a little bit confused about that chapter. Does assert do the same job?