Difference between revisions of "Coding Style Guidelines"
(→Clean Code) |
(→Clean LaTeX) |
||
| (12 intermediate revisions by the same user not shown) | |||
| Line 15: | Line 15: | ||
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. | 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. | ||
| − | + | Tabs or spaces? Use what the existing code has. | |
| − | + | ||
| − | + | ||
==Revision Control== | ==Revision Control== | ||
| Line 37: | Line 35: | ||
If you think that one of these summaries is unclear, please fix it. | If you think that one of these summaries is unclear, please fix it. | ||
| − | Chapter 1: Leave the code | + | ===Chapter 1: Boy Scout Rule=== |
| + | |||
| + | '''Leave the code cleaner than it was before.''' Never leave temporary code, make other code better than it was before. | ||
| + | |||
| + | |||
| + | ===Chapter 2: Names=== | ||
| + | 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. | ||
| + | |||
| + | 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. | ||
| + | |||
| + | ===Chapter 3: Functions=== | ||
| + | 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: Comments=== | ||
| + | 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: Formatting=== | ||
| + | Abstraction should occur top-down. Conceptual affinity (declarations near use). Keep line lengths short(< 100 characters and wrapped). Indent to improve readability. Follow conventions in existing code. | ||
| + | |||
| + | ===Chapter 6: Objects and Data Structures=== | ||
| + | Objects should expose behavior but not implementation. Data structures expose data. Do not combine them. Law of Demeter: Module should not know about innards of object it manipulates. Do not mix levels of abstraction. | ||
| + | |||
| + | ===Chapter 7: Error handling=== | ||
| + | Use exceptions when possible, but don't let them obscure the normal code. Don't return null, don't pass null. | ||
| + | |||
| + | ===Chapter 8: Boundaries=== | ||
| + | Generally add wrappers to third party code so that it can be replaced and/or intercepted. | ||
| + | |||
| + | ===Chapter 9: Unit Tests=== | ||
| + | Keep tests clean. One assertion per test, single concept per test. FIRST = Fast, Independent, Repeatable, Self-Validating, Timely. I add: Your code isn't done until you have a test. | ||
| + | |||
| + | ===Chapter 10: Classes=== | ||
| + | Classes should be small (have a single responsibility). | ||
| + | |||
| + | ==Clean LaTeX== | ||
| + | |||
| + | The above ideas of clean code also apply to LaTeX documents. '''Using these hints will also make combining papers into your thesis easier!''' Here is some additional information: | ||
| + | |||
| + | Wrap all paragraphs to 100 characters or less. | ||
| + | |||
| + | New paragraphs are started with a blank line, not with \\. | ||
| + | |||
| + | Make sure to use vertical spacing. Space between figures, equations, paragraphs, section titles, etc. This lets latex know what is a paragraph and how to lay out the images in text. | ||
| + | Labels for figures should go inside the caption. Otherwise, this can mess up the number in certain situations. | ||
| − | + | Do not leave extraneous comments. However, I often find it useful to have a comment that summarizes what an entire paragraph should be about. This is usually from my initial outline. | |
| + | Paragraphs should be short and to the point, much like functions. As above, the paragraph should relate to a single bullet in your outline, no more, no less. | ||
| − | + | Never hard-code references to sections, figures, etc. These should be dynamically updated using \label and \ref commands. | |
| − | + | Labels should use a prefix to aid in understanding what they are. Remember the clean code guidelines about useful names. For example, | |
| + | \label{fig:area_vs_power} | ||
| + | \label{tab:synthesis_results} | ||
| + | \label{sec:conclusions} | ||
| − | |||
| − | + | Also, multiple references should be in a single cite like this: | |
| + | \cite{Sathe:2013,Chen:1991} | ||
| + | not this: | ||
| + | \cite{Sathe:2013},\cite{Chen:1991} | ||
| + | The formatting will be taken care of by the biblio style. | ||
| − | + | You should often use a ~ (non-breaking space) to make sure that a citation or reference does not dangle/get pushed to the next line. For example, | |
| + | and the results are summarized in Table~\ref{tab:results}. | ||
| − | + | You should use the built in section, list, etc. styles. These are decided in the style class and are automatically changed when you change that style. If you manually create your own style using sizes (\Large), bold face (\bf), etc. it will need to be manually updated when converting between styles (e.g. between ACM, IEEE formats or your thesis format). | |
Latest revision as of 17:19, 26 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.
Tabs or spaces? Use what the existing code has.
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: Boy Scout Rule
Leave the code cleaner than it was before. Never leave temporary code, make other code better than it was before.
Chapter 2: Names
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.
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.
Chapter 3: Functions
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: Comments
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: Formatting
Abstraction should occur top-down. Conceptual affinity (declarations near use). Keep line lengths short(< 100 characters and wrapped). Indent to improve readability. Follow conventions in existing code.
Chapter 6: Objects and Data Structures
Objects should expose behavior but not implementation. Data structures expose data. Do not combine them. Law of Demeter: Module should not know about innards of object it manipulates. Do not mix levels of abstraction.
Chapter 7: Error handling
Use exceptions when possible, but don't let them obscure the normal code. Don't return null, don't pass null.
Chapter 8: Boundaries
Generally add wrappers to third party code so that it can be replaced and/or intercepted.
Chapter 9: Unit Tests
Keep tests clean. One assertion per test, single concept per test. FIRST = Fast, Independent, Repeatable, Self-Validating, Timely. I add: Your code isn't done until you have a test.
Chapter 10: Classes
Classes should be small (have a single responsibility).
Clean LaTeX
The above ideas of clean code also apply to LaTeX documents. Using these hints will also make combining papers into your thesis easier! Here is some additional information:
Wrap all paragraphs to 100 characters or less.
New paragraphs are started with a blank line, not with \\.
Make sure to use vertical spacing. Space between figures, equations, paragraphs, section titles, etc. This lets latex know what is a paragraph and how to lay out the images in text.
Labels for figures should go inside the caption. Otherwise, this can mess up the number in certain situations.
Do not leave extraneous comments. However, I often find it useful to have a comment that summarizes what an entire paragraph should be about. This is usually from my initial outline.
Paragraphs should be short and to the point, much like functions. As above, the paragraph should relate to a single bullet in your outline, no more, no less.
Never hard-code references to sections, figures, etc. These should be dynamically updated using \label and \ref commands.
Labels should use a prefix to aid in understanding what they are. Remember the clean code guidelines about useful names. For example,
\label{fig:area_vs_power}
\label{tab:synthesis_results}
\label{sec:conclusions}
Also, multiple references should be in a single cite like this:
\cite{Sathe:2013,Chen:1991}
not this:
\cite{Sathe:2013},\cite{Chen:1991}
The formatting will be taken care of by the biblio style.
You should often use a ~ (non-breaking space) to make sure that a citation or reference does not dangle/get pushed to the next line. For example,
and the results are summarized in Table~\ref{tab:results}.
You should use the built in section, list, etc. styles. These are decided in the style class and are automatically changed when you change that style. If you manually create your own style using sizes (\Large), bold face (\bf), etc. it will need to be manually updated when converting between styles (e.g. between ACM, IEEE formats or your thesis format).
