Coding Standard Framework

At Northwestern, lots of teams are using lots of different programming languages, tools, frameworks, and libraries to build a diverse set of applications.

The SDCC cannot provide specific guidance for every technology. Instead, we provide common standards that are broadly applicable, a framework for building a tech-stack-specific coding standard, and a repository of “known good” coding standards.

Goals

The purpose of these coding standards is to provide for a common set of “core functionality” and commonality between IT@NU applications. This is useful for a few reasons:

Consistent tools/checks across IT@NU, so developers working cross-project can safely & confidently contribute.
Consistent code formatting in a project, so diffs between versions are legible for code review.
Consistent developer documentation in each project, so developers can “drop in” from different units and know how to get set up & collaborate on a project.
Mandated tools/checks for certain security- & compliance-related items, like web accessibility.
Consistency in logging some types of events & dependency management, so the Information Security office can mount an effective response during an incident.

Scope

The coding standards are oriented towards custom development in traditional programming languages: building your own application with something like PHP, Java, .NET, or Python. When developing custom software, the general coding standard and applicable stack-specific standards SHOULD be followed.

These standards are not applicable to proprietary vendor ecosystems. None of this will make sense for a low-code tool like Power Automate, for example. But, depending on usage, some of this could be applicable to a programmable platform like Salesforce. Developers SHOULD consider what standards, if any, are applicable to vendor & SaaS products.

Application Types

Broadly, the standards consider three main types of applications:

Web: static or dynamic sites accessed through a browser.
Libraries: reusable components meant for other developers.
Data Integrations: standalone backend processes that move or transform data, without directly offering an end-user experience.
Console: command-line applications, often for one-off internal things or infrastructure glue code.

These MAY have different coding standards. For example: web applications will always need to be WCAG 2.1 AA compliant, but this standard is not applicable to a data integration.

Contributing

Standards for specific tech stacks should be developed and maintained by team(s) actively using those languages, frameworks, and tools. Any unit is welcome to contribute new stack standards or suggest changes to an existing document. There is a _template.mdx file you can copy to get started.

These are shared standards for all developers at Northwestern. Other units may be using the same technologies differently. In these cases, differences should be discussed among users and a consensus formed. There may be a “right” answer that groups can agree on, or there may be multiple “right” answers that the standard can provide guidance for selecting.

Tech stack documents SHOULD align to the structure of the General Coding Standards document. They can omit sections if they are not applicable, and add sections where additional clarity is useful. But, for ease of translating the general standards into more specific recommendations, strive to repeat the same headings.

There does not need to be a single ‘PHP’ standards document. For example, despite all being PHP, Laravel, WordPress, and Drupal applications have different tools, norms, problems. WordPress developers MAY create their own document instead of trying to make the PHP/Laravel standard the be-all-end-all of PHP.

Governance

Once a tech stack document has been initialized, the original author(s) become the maintainers of the document via the CODEOWNERS file in the GitHub repository. They MUST approve any content¹ changes.

The maintainers are free to add additional members as they see fit. The SDCC team may seek a new maintainer if a standard document is abandoned.

Authoring for Everyone

Editors should aim to make the standards broadly applicable to the IT@NU community.

Make heavy use of ‘SHALL’ and ‘MAY’: these provide “reasonable defaults” to developers, but allow for flexibility when needed.

The use of ‘MUST’ (or ‘MUST NOT’) should be reserved for items that are non-negotiable. For example, web applications MUST be WCAG 2.1 AA compliant because of an approved university-wide policy. That policy establishes it as a baseline requirement.

Consensus

Maintainers SHOULD be connected to their constituents and strive to create consensus. They MAY circulate early drafts for feedback, or @ people into the GitHub pull request for discussion.

There will occasionally be controversial items. Maintainers SHOULD strive for consensus, much like a Wikipedia editor under their WP:CON policy.

If an item has major differences in opinion, remember that ‘SHOULD’ is not the same as ‘MUST’. Even when some contributors have a reason to deviate, the document SHOULD still recommend one or two known-good options via a ‘SHOULD’ or ‘MAY’.

When there are major differences of opinion, that MAY indicate the item in question should not be in the standard, or multiple options should be provided. When there are several possible options, some criteria for selection should be given, so other readers will know how to navigate that choice.

The SDCC team will not arbitrate content disputes. Maintainers, editors, and other users of that tech stack should build consensus to accept changes.

The SDCC team may fast-track technical changes necessary for the continued function of the site. For example, adjusting imports for components during an upgrade, or applying consistent styling. They will not change the standards themselves without approval from the appropriate maintainers. ↩