style_guide.lyx

CNC 的开放码,EMC2 V2.2.8版

#LyX 1.3 created this file. For more info see http://www.lyx.org/
\lyxformat 221
\textclass book
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\use_natbib 0
\use_numerical_citations 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation skip
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Chapter

Coding Style
\layout Standard

This chapter describes the source code style prefered by the EMC team.
\layout Section

Do no harm
\layout Standard

When making small edits to code in a style different than the one described
 below, observe the local coding style.
 Rapid changes from one coding style to another decrease code readability.
\layout Standard

Never check in code after running 
\begin_inset Quotes eld
\end_inset 

indent
\begin_inset Quotes erd
\end_inset 

 on it.
 The whitespace changes introduced by indent make it more difficult to follow
 the revision history of the file.
\layout Standard

Do not use an editor that makes unneeded changes to whitespace (e.g., which
 replaces 8 spaces with a tabstop on a line not otherwise modified, or word-wrap
s lines not otherwise modified)
\layout Section

Tab Stops
\layout Standard

A tab stop always corresponds to 8 spaces.
 Do not write code that displays correctly only with a differing tab stop
 setting.
\layout Section

Indentation
\layout Standard

Use 4 spaces per level of indentation.
 Combining 8 spaces into one tab is acceptable but not required.
\layout Section

Placing Braces
\layout Standard

Put the opening brace last on the line, and put the closing brace first:
\layout LyX-Code

if(x) { 
\newline 
   f();
\newline 
}
\layout Standard

The closing brace is on a line of its own, except in the cases where it
 is followed by a continuation of the same statement, i.e.
 a "while" in a do-statement or an "else" in an if-statement, like this:
\layout LyX-Code

do {
\newline 
   body();
\newline 
} while (condition);
\layout Standard

and
\layout LyX-Code

if(x == y) { 
\newline 
   ..
 
\newline 
} else if(x > y) { 
\newline 
   ...
\newline 
} else { 
\newline 
   ....
\newline 
}some detail 
\layout Standard

This brace-placement also minimizes the number of empty (or almost empty)
 lines, which allows a greater amount of code or comments to be visible
 at once in a terminal of a fixed size.
\layout Section

Naming
\layout Standard

C is a Spartan language, and so should your naming be.
 Unlike Modula-2 and Pascal programmers, C programmers do not use cute names
 like ThisVariableIsATemporaryCounter.
 A C programmer would call that variable "tmp", which is much easier to
 write, and not the least more difficult to understand.
 
\layout Standard

However, descriptive names for global variables are a must.
 To call a global function "foo" is a shooting offense.
 
\layout Standard

GLOBAL variables (to be used only if you 
\series bold 
really
\series default 
 need them) need to have descriptive names, as do global functions.
 If you have a function that counts the number of active users, you should
 call that "count_active_users()" or similar, you should 
\series bold 
not
\series default 
 call it "cntusr()".
 
\layout Standard

Encoding the type of a function into the name (so-called Hungarian notation)
 is brain damaged - the compiler knows the types anyway and can check those,
 and it only confuses the programmer.
 No wonder Microsoft makes buggy programs.
 
\layout Standard

LOCAL variable names should be short, and to the point.
 If you have some random integer loop counter, it should probably be called
 "i".
 Calling it "loop_counter" is non-productive, if there is no chance of it
 being mis-understood.
 Similarly, "tmp" can be just about any type of variable that is used to
 hold a temporary value.
 
\layout Standard

If you are afraid to mix up your local variable names, you have another
 problem, which is called the function-growth-hormone-imbalance syndrome.
 See next chapter.
 
\layout Section

Functions
\layout Standard

Functions should be short and sweet, and do just one thing.
 They should fit on one or two screenfuls of text (the ISO/ANSI screen size
 is 80x24, as we all know), and do one thing and do that well.
 
\layout Standard

The maximum length of a function is inversely proportional to the complexity
 and indentation level of that function.
 So, if you have a conceptually simple function that is just one long (but
 simple) case-statement, where you have to do lots of small things for a
 lot of different cases, it's OK to have a longer function.
 
\layout Standard

However, if you have a complex function, and you suspect that a less-than-gifted
 first-year high-school student might not even understand what the function
 is all about, you should adhere to the maximum limits all the more closely.
 Use helper functions with descriptive names (you can ask the compiler to
 in-line them if you think it's performance-critical, and it will probably
 do a better job of it that you would have done).
 
\layout Standard

Another measure of the function is the number of local variables.
 They shouldn't exceed 5-10, or you're doing something wrong.
 Re-think the function, and split it into smaller pieces.
 A human brain can generally easily keep track of about 7 different things,
 anything more and it gets confused.
 You know you're brilliant, but maybe you'd like to understand what you
 did 2 weeks from now.
 
\layout Section

Commenting
\layout Standard

Comments are good, but there is also a danger of over-commenting.
 NEVER try to explain HOW your code works in a comment: it's much better
 to write the code so that the 
\series bold 
working
\series default 
 is obvious, and it's a waste of time to explain badly written code.
 
\layout Standard

Generally, you want your comments to tell WHAT your code does, not HOW.
 A boxed comment describing the function, return value, and who calls it
 placed above the body is good.
 Also, try to avoid putting comments inside a function body: if the function
 is so complex that you need to separately comment parts of it, you should
 probably re-read the Functions section again.
 You can make small comments to note or warn about something particularly
 clever (or ugly), but try to avoid excess.
 Instead, put the comments at the head of the function, telling people what
 it does, and possibly WHY it does it.
\layout Standard

If comments along the lines of /* Fix me */ are used, please, please, say
 why something needs fixing.
 When a change has been made to the affected portion of code, either remove
 the comment, or amend it to indicate a change has been made and needs testing.
\layout Section

Shell Scripts & Makefiles 
\layout Standard

Not everyone has the same tools and packages installed.
 Some people use vi, others emacs - A few even avoid having either package
 installed, preferring a lightweight text editor such as nano or the one
 built in to Midnight Commander.
\layout Standard

gawk versus mawk - Again, not everyone will have gawk installed, mawk is
 nearly a tenth of the size and yet conforms to the Posix AWK standard.
 If some obscure gawk specific command is needed that mawk does not provide,
 than the script will break for some users.
 The same would apply to mawk.
 In short, use the generic awk invocation in preference to gawk or mawk.
\layout Section

CVS 
\layout Subsection

Notes
\layout Standard

cvs is such a powerful tool that many developers fail to use to its full
 potential.
 http://www.red-bean/cvsbook should be compulsory reading for anyone wanting
 to use cvs.
 The chapters on tags, branching, and merging can appear daunting at first,
 so should be read several times.
 Chapters covering administration, however, can be skipped.
\layout Subsection

CVS Commit Comments
\layout Standard

When committing a change or file to the repository, a short note describing
 the change is helpful for future reference.
 "A small bug fix to foo" is more informative than a "." (which should be
 another shooting offense).
\layout Standard

The most important thing to put in the log is WHY you made this change.
 To say "removed some code" or "renamed some things" serves no purpose because
 the reader can see the exact change for himself.
 What he can't do is read your mind and see why you made the change.
 If you intend that this change fixes a bug, say what the bug was.
 If it's in the tracker, give the bug number.
\layout Subsection

CVS Tags
\layout Standard

Tagging files within the cvs repository enables us to mark a set of files
 with a specific marker.
 This provides a simple mechanism to retrieve code thus marked.
 The tags could indicate a stable version, or be a precursor to branching.
 Apart from branch tags, the recommendation is to prefix all tags with the
 developers initials.
 Note: Tags prefixed with bdi or BDI are reserved for use in conjunction
 with the Brain Dead Install project.
\layout Subsection

CVS Special Keywords
\layout Standard

There are certain special CVS keywords that can be used inside a document.
 However, it is a bad habit to include information that clutters the source
 file.
 One such example is the $Log directive; that information is stored in the
 CVS server and can easily be viewed with the web interface or the cvs client.
 
\layout Section

C++ Conventions
\layout Standard

C++ coding styles are always likely to end up in heated debates (a bit like
 the emacs versus vi arguments).
 One thing is certain however, a common style used by everyone working on
 a project leads to uniform and readable code.
\layout Standard

Naming conventions: Constants either from #defines or enumerations should
 be in upper case through out.
 Rationale: Makes it easier to spot compile time constants in the source
 code.
 e.g.
 EMC_MESSAGE_TYPE
\layout Standard

Classes and Namespaces should capitalize the first letter of each word and
 avoid underscores.
 Rationale: Identifies classes, constructors and destructors.
 e.g.
 GtkWidget
\layout Standard

Methods (or function names) should follow the C recommendations above and
 should not include the class name.
 Rationale: Maintains a common style across C and C++ sources.
 e.g.
 get_foo_bar()
\layout Standard

However, boolean methods are easier to read if they avoid underscores and
 use an 'is' prefix (not to be confused with methods that manipulate a boolean).
 Rationale: Identifies the return value as TRUE or FALSE and nothing else.
 e.g.
 isOpen, isHomed
\layout Standard

Do NOT use "Not" in a boolean name, it leads only leads to confusion when
 doing logical tests.
 e.g.
 isNotOnLimit or is_not_on_limit are BAD.
\layout Standard

Variable names should avoid the use of upper case and underscores except
 for local or private names.
 The use of global variables should be avoided as much as possible.
 Rationale: Clarifies which are variables and which are methods.
 Public: e.g.
 axislimit Private: e.g.
 maxvelocity_
\layout Standard

Specific method naming conventions
\layout Standard

The terms get and set should be used where an attribute is accessed directly.
 Rationale: Indicates the purpose of the function or method.
 e.g.
 get_foo set_bar
\layout Standard

For methods involving boolean attributes, set & reset is preferred.
 Rationale: As above.
 e.g.
 set_amp_enable reset_amp_fault
\layout Standard

Math intensive methods should use compute as a prefix.
 Rationale: Shows that it is computationally intensive and will hog the
 CPU.
 e.g.
 compute_PID
\layout Standard

Abbreviations in names should be avoided where possible - The exception
 is for local variable names.
 Rationale: Clarity of code.
 e.g.
 pointer is preferred over ptr compute is preferred over cmp compare is
 again preferred over cmp.
\layout Standard

Enumerates and other constants can be prefixed by a common type name e.g.
 enum COLOR { COLOR_RED, COLOR_BLUE };
\layout Standard

Excessive use of macros and defines should be avoided - Using simple methods
 or functions is preferred.
 Rationale: Improves the debugging process.
\layout Standard

Include Statements Header files must be included at the top of a source
 file and not scattered throughout the body.
 They should be sorted and grouped by their hierarchical position within
 the system with the low level files included first.
 Include file paths should NEVER be absolute - Use the compiler -I flag
 instead.
 Rationale: Headers may not be in the same place on all systems.
\layout Standard

Pointers and references should have their reference symbol next to the variable
 name rather than the type name.
 Rationale: Reduces confusion.
 e.g.
 float *x or int &i
\layout Standard

Implicit tests for zero should not be used except for boolean variables.
 e.g.
 if (spindle_speed != 0) NOT if (spindle_speed)
\layout Standard

Only loop control statements must be included in a for() construct.
 e.g.
 sum = 0; for (i = 0; i < 10; i++) { sum += value[i]; }
\layout Standard

NOT for (i = 0, sum =0; i < 10; i++) sum += value[i];
\layout Standard

Likewise, executable statements in conditionals must be avoided.
 e.g.
 if (fd = open(file_name) is bad.
\layout Standard

Complex conditional statements should be avoided - Introduce temporary boolean
 variables instead.
\layout Standard

Parentheses should be used in plenty in mathematical expressions - Do not
 rely on operator precedence when an extra parentheses would clarify things.
\layout Standard

File names: C++ sources and headers use .cc and .hh extension.
 The use of .c and .h are reserved for plain C.
 Headers are for class, method, and structure declarations, not code (unless
 the functions are declared inline).
 
\layout Section

Python coding standards
\layout Standard

Use the 
\begin_inset LatexCommand \url[PEP 8]{http://www.python.org/dev/peps/pep-0008/}

\end_inset 

 style for Python code.
\layout Section

Comp coding standards
\layout Standard

In the declaration portion of a .comp file, begin each declaration at the
 first column.
 Insert extra blank lines when they help group related items.
\layout Standard

In the code portion of a .comp file, follow normal C coding style.
\the_end