Coding Standards

Table of Contents

• Coding Standards
  1. Introduction
  2. File System Management
     • File Naming Conventions
     • Directory Tree Structure
     • Versioning Files
  3. Naming Conventions
     • Naming Style
     • Demographic Data
     • Assessment Data
  4. Documenting Code
     • Literate Programming
     • File Headers
     • Block Comments
     • In-line Comments
  5. Development Guidance
     • Reusability
     • Replicability
     • Reliability
     • Responsibility
  6. Version Control
     • Git: Live it, Learn it, Love it
     • Repository Initialization
     • Staging Code for Commit
     • Committing Code to Repository
     • Pushing Changes to Remote Repository
     • Getting Changes from Remote Repository
     • Combining Changes from Other Repositories/Branches
     • Pull Requests
     • Code Contributions
  7. Style Guides
     • Stata
     • R
     • Java
     • SQL
     • Bash
     • Python
     • Batch
  8. Code Reviews
     • Reviewing Code
     • Checking Style
     • QA/QC
  9. Collecting Business Rules
     • User Stories
     • Epics
     • Projects
  10. Testing
      • Unit Testing
      • Regression Tests
      • User Acceptance Testing

Coding Standards

Back to the Top Back to Table of Contents

1. Introduction

Back to the Top Back to Table of Contents

2. File System Management

Back to the Top Back to Table of Contents

File Naming Conventions

Back to the Top Back to beginning of Section Back to Table of Contents

Directory Tree Structure

Back to the Top Back to beginning of Section Back to Table of Contents

Versioning Files

Back to the Top Back to beginning of Section Back to Table of Contents

3. Naming Conventions

In this section, we describe the naming conventions used for raw and aggregated data. These conventions can be expected to be stable over time and are intended for use by FCPS staff and research partners.

Back to the Top Back to Table of Contents

Naming Style

Whenever possible, we will try to use the fewest characters possible to unambiguously identify a datum. This often requires several combinations of letters to be used in order to construct standardized names conforming to our naming conventions. The sections below provide information about cases where static definitions exist (e.g., Demographic Data) and cases where the names are constructed from combinations of discrete pieces of information to identify the meaning of the datum (e.g., Assessment Data). There are some common elements that are used to construct meaning as prefix or suffix elements:

Table. Common Prefixes and Suffixes Used in Naming Conventions

Back to the Top Back to beginning of Section Back to Table of Contents

Demographic Data

The table below shows the names given to attributes used to reference demographic data.

Table. Demographic naming conventions

Back to the Top Back to beginning of Section Back to Table of Contents

Assessment Data

We use a simple grammar for our assessment variables that can be defined with a regular expression: (([a-z]{3}){2}) ([a-z]{2,3})([0-9]{1,2})?(item[0-9]{1,2})?. This expression translates into a grammar to represent discrete pieces of the information that can be used to uniquely identify the data of interest: testCode + subjectCode + scoreCode [ + # ] [ + item# ]; in this example, we use the square brackets to denote optional information that is used to extend the base grammar to additional use cases.

We’ve provided some tables below that can help you to understand the naming conventions based on the grammatical role identified previously (e.g., testCode, subjectCode, etc…).

Table. testCode values and descriptors.

Table. subjectCode values and descriptors.

Table. scoreCode values and descriptors.

Back to the Top Back to beginning of Section Back to Table of Contents

4. Documenting Code

Back to the Top Back to Table of Contents

Literate Programming

Back to the Top Back to beginning of Section Back to Table of Contents

File Headers

Back to the Top Back to beginning of Section Back to Table of Contents

Block Comments

Back to the Top Back to beginning of Section Back to Table of Contents

In-line Comments

Back to the Top Back to beginning of Section Back to Table of Contents

5. Development Guidance

Back to the Top Back to Table of Contents

Reusability

Back to the Top Back to beginning of Section Back to Table of Contents

Replicability

Back to the Top Back to beginning of Section Back to Table of Contents

Reliability

Back to the Top Back to beginning of Section Back to Table of Contents

Responsibility

Back to the Top Back to beginning of Section Back to Table of Contents

6. Version Control

Back to the Top Back to Table of Contents

Git: Live it, Learn it, Love it

Back to the Top Back to beginning of Section Back to Table of Contents

Repository Initialization

Back to the Top Back to beginning of Section Back to Table of Contents

Staging Code for Commit

Back to the Top Back to beginning of Section Back to Table of Contents

Committing Code to Repository

Back to the Top Back to beginning of Section Back to Table of Contents

Pushing Changes to Remote Repository

Back to the Top Back to beginning of Section Back to Table of Contents

Getting Changes from Remote Repository

Back to the Top Back to beginning of Section Back to Table of Contents

Combining Changes from Other Repositories/Branches

Back to the Top Back to beginning of Section Back to Table of Contents

Pull Requests

Back to the Top Back to beginning of Section Back to Table of Contents

Code Contributions

Back to the Top Back to beginning of Section Back to Table of Contents

7. Style Guides

Back to the Top Back to Table of Contents

Stata

Back to the Top Back to beginning of Section Back to Table of Contents

R

Back to the Top Back to beginning of Section Back to Table of Contents

Java

Back to the Top Back to beginning of Section Back to Table of Contents

SQL

Back to the Top Back to beginning of Section Back to Table of Contents

Bash

Back to the Top Back to beginning of Section Back to Table of Contents

Python

Back to the Top Back to beginning of Section Back to Table of Contents

Batch

Back to the Top Back to beginning of Section Back to Table of Contents

8. Code Reviews

Back to the Top Back to Table of Contents

Reviewing Code

Back to the Top Back to beginning of Section Back to Table of Contents

Checking Style

Back to the Top Back to beginning of Section Back to Table of Contents

9. QA/QC

Back to the Top Back to beginning of Section Back to Table of Contents

Collecting Business Rules

Back to the Top Back to Table of Contents

User Stories

Back to the Top Back to beginning of Section Back to Table of Contents

Epics

Back to the Top Back to beginning of Section Back to Table of Contents

Projects

Back to the Top Back to beginning of Section Back to Table of Contents

10. Testing

Back to the Top Back to Table of Contents

Unit Testing

Back to the Top Back to beginning of Section Back to Table of Contents

Regression Tests

Back to the Top Back to beginning of Section Back to Table of Contents

User Acceptance Testing

Back to the Top Back to beginning of Section Back to Table of Contents