Stata do file Style Guide

(work in progress)

Statdoc tries to extract as much information out of existing do files as possible. However there are a few rules, that make its job much easier.

1. Use a descriptive document comment in the header.

---

Statdoc supports javadoc style comments (enclosed in /** */, note the double ** to differentiate it from a normal comments). For the header information they follow this format:

/**

A one line description of what this do file does.
Followed by more description if necessary to clarify how it works

@author Name of Author(s)
@otherinfo Additional key-value descriptors of the do file, e.g. date, urls, documents...

*/

2. Use relative paths

---

To help statdoc to properly identify files, use a single cd command at the beginning to switch the project's root directory and use relative paths for all files within afterwards. Use fully specified paths for all files that reside outside of the project directory.

3. Use quotes " around paths and file names

---

Always enclose paths and filenames in quotes to allow Statdoc to properly identify them. Usually it is also good advice to avoid spaces and special characters (except maybe _) in paths and file names.

4. Use forward slashes "/" instead of backward slashes "" in path names

---

As do files are able to run on multiple platforms, the format of the path matters. Since unfortunately backward slashes cause problems on *nix based platforms, using forward slashes is the only platform independent way to make this work.

5. Don't use keywords as variable names

---

There are a few keywords that are best avoided as variable names such as if, using, weight as it might confuse the parser. It is also recommended to use unique, descriptive variable names that do not denote common Stata commands.

6. Use // instead of * to mark one-line comments

---

The star sign (*) is heavily overloaded with functionality in Stata, it denotes multiplication, variable name wildcards and comments. In the environment of Statdoc where the full data set is not necessarily known at the time of parsing this can lead to ambigious results, if in doubt, Statdoc will consider * as NOT comment indicators. Hence use // whenever possible.

7. Write a single log file per do file

---

Statdoc will automatically link up the log file to this do file.