We are currently in the process of putting into place stricter code style conventions for our Java code, so it is appropriate that we start setting down similar conventions for our Typescript code. This issue is for proposing a set of such conventions.

This proposal assumes these policies build on the conventions set out for Angular projects (e.g. file naming conventions, class naming conventions, etc.). Exceptions to conventions are expected (but rare) to improve readability.

Spacing

Indentation and Line Length

1. Standard indentation is 4 spaces; indentation must not include TAB (Ctrl-I) characters.
2. Avoid statements longer than 120 characters. Longer statements should be either continued onto another line with line-breaks that optimize readability or otherwise broken into multiple, shorter statements.
3. The last character of a source file should be a new-line (i.e. "return") character.

Classes, Functions, and Decorators

1. Each decorator of a class, function, or variable (e.g. @Component({...) should begin on a new line.
2. Decorators should be considered conceptually part of signature line they decorate: there should be no blank line between a decorator block and it class of function signature.
3. When a decorator includes with an object argument (e.g. {...}), each property of the object should appear on
   a separate line and be indented by the standard amount (4); the closing object brace ({) and parenthesis (() should appear on its own line.

This example illustrates the above three recommendations:

@Component({
    moduleId: module.id,
    selector: 'pdr-headbar',
    templateUrl: 'headbar.component.html',
    styleUrls: ['headbar.component.css']
})
export class HeadbarComponent {

4. When a function signature fits on one line, the opening brace ({) should appear on the same line as the signature. In this case, it is recommended that a blank line be inserted after after the brace and before the first line of the body for better readability.
5. When a function signature does not fit on a single line:
   • continue signature on multiple lines, breaking after the comma following an argument
   • subsequent argument lines should be indented to the column that the first argument appears in.
   • the closing function parenthesis should appear on the same line as the last argument
   • the opening function body brace should appear on its own line, aligned with the start of the function signature.
   • the return type may appear on the same line as the last argument or on its own line; in the latter case, it should be indented four spaces from the start of the function signature

Multi-line function signature:

    public setDownloadStatus(resid: string, filePath: string, 
                             downloadedStatus: string = "downloaded") : boolean 
    {
        this.restore();

6. When a class signature fits on one line, the opening brace should appear on the same line as the signature. In this case, it is recommended that a blank line be inserted after after the brace and before the first line of the body for better readability.

Comments and Documentation

The term "in-line documentation" here is intended to to refer to comment blocks that could be extracted and converted into human-readable API documentation (like with javadoc for Java code). We do not currently use a documentation extractor with our Typescript code; however, we may in the future. Nevertheless, extractable documentation markup is on can be highly readable and provides conventions for indicating what is being described.

1. In-line class, interface, function, and variable documentation should follow the Java in-line documentation conventions, using /** ... */ comment blocks.
2. In-line class, interface, function, and variable documentation should appear immediately above both the signature and any decorators; the comment opener, /**, should be indented to align with the start of the class, interface, function, or variable.

This example illustrates the above two recommendations:

/**
 * a data structure describing a file in the cart.  A CartEntryData object, in effect, is a NerdmComp 
 * that *must* have the filePath property and is expected to have some additional 
 * data cart-specific properties.  
 */
export interface DataCartItem {

    /**
     * a local identifier for resource.  This must not start with an underscore as this is reserved.  
     */
    resId? : string;

3. In-line function documentation is recommended for any function marked with the public modifier.
4. In-line class documentation is recommended for any exported class, interface or function.
5. In-line variable documentation is recommended for properties of an exported interface.
6. In-line class documentation is highly recommended for any exported component class (i.e., marked with the @Component decorator). It should briefly summarize what visually appears in the component when it is rendered.

Example Component documentation:

/**
 * A component for displaying access to landing page tools in a menu.
 * 
 * Items include:
 * * links to the different sections of the landing page
 * * links to view or export metadata
 * * information about usage (like Citation information in a pop-up)
 * * links for searching for similar resources
 */
@Component({
    selector: 'tools-menu',
    template: ;tools-menu.html',
    styleUrls: ['./toolmenu.component.css']
})
export class ToolMenuComponent implements OnChanges {

The metadata/docker directory contains Docker containers for installing all the needed dependencies and running the metadata tests. We found that the container that installs jq is failing because of a failed checksum. This occurs when the repository is cloned from usnistgov/oar-pdr.

The metadata/docker/jq directory contains the files for building the jq container. The Dockerfile downloads jq as a binary from the official jq site, so it also does a checksum check on the downloaded executable. A file storing the binary's checksum, jq-sha256sum.txt, is included in the jq directory. To check for unexpected (or malicious) changes to the checksum file, a checksum check is also done on the checksum file, comparing the checksum file in our repository with the one on the jq web site. Unfortunately, git will sometimes convert line-feeds in text files between the LF and CRLF conventions, depending on the platform one is working on. This has occurred somewhere in the merging into the integration branch. As a result, the file is not exactly the same as the checksum file at the jq website, and the checksum fails.

This extra test of the checksum file is probably redundant and can be removed. It was meant catch unnoticed changes not only in the binary but also in the checksum file either in the repo or at its original website, but on further reflection, I'm not sure it is providing any extra protection over just having a copy of the checksum file in the repo.

We made some (nominally) NERDm records and uploaded to the dev API, and they were accepted. It was only when trying to render them with the angular server /lps endpoint that we discovered a problem - the page returned an error and did not render the record. The error trace said something about a value being undefined.

After some slow investigation and looking at the schema, I found that a) the problem was caused by us not complying with the schema and b) it was because records contained the top-level key "keywords": string[] instead of the required "keyword": string[]

We already made the change to use the key keyword on our end, but I wonder what the appropriate place to validate the records is? At render-time is not ideal. Would it make sense to validate as part of the ingestion, returning an error if the record does not match the schema? I feel like that is a better guarantee of consistency than asking submitters to validate before PUT/PATCH on a record.

withdrawn

I'm just wondering why every government agency needs to have a different one of these...

• https://github.com/pacifica/pacifica (the one I work on)
• https://github.com/ckan/ckan (other gov agencies)
  • https://github.com/GSA/data.gov/ (with some word press?)
• https://github.com/GetDKAN/dkan2 (Drupal CKAN)
• https://github.com/nasa/data-nasa-gov-frontpage (It'd be nice to know what's behind this)
• https://github.com/doecode/doecode (code repo but holds data too)
• There's more NIH has a bunch
• https://github.com/ARM-DOE/

It'd be nice to have a standard way government can build a data repository, so we can all use the same technology in the same way.