Code annotation

Tier 2 · Executable - Silver recommended

The code is commented and structured so that a reader can follow what each part does: script headers state purpose, inputs and outputs, and comments show which section produces which table or figure.

Rating

Met

Every script has a header stating its purpose, inputs and outputs; the code is commented throughout so that a reader who does not use the software can follow each section; and comments indicate which section produces which table or figure.

Partially met

Comments are present but incomplete: e.g. some scripts lack headers, comments are sparse or outdated, or there is no link between code sections and the tables/figures they produce.

Not met

The code has no meaningful comments or headers; a reader can only find out what it does by reverse-engineering it.

Based on: #70 ‘if you did not document your code … fail’, #83 correspondence between code and figures, #108 coding conventions, comments, white space, #128 well-structured and comprehensible, #10 explanation for human readers.

Not applicable

Never.

Prerequisites

Check order: 2

Builds on

Code deposit (1 source)

Prerequisite for

Codes consistent with claims (1 source)

In the corpus

Sources	Injunctive	Descriptive	Tacit	Automatable	Manual check	Automation unclear	LLM sources
6	83.3%	0%	16.7%	0%	0%	100%	0

Text evidence (6 quotes)

Show quotes

#10 Sustainable computational science: the ReScience initiative · injunctive

“…an explanation of this code for human readers” (p.7)

#70 The Stark realities of reproducible statistically orientated sociological research: Some newer rules of the sociological method · injunctive

“If you did not document your code so that others can read and understand it, fail.” (Table 1, p.210)

#83 Reproducibility and transparency versus privacy and confidentiality: Reflections from a data editor · injunctive

“Program code and command files should be annotated to facilitate replication and ensure clear correspondence between code and figures.” (slide “Tools and Guidance” — Depositing Data section)

#108 Checklists for computational reproducibility in social sciences: insights from literature and survey evaluation · injunctive

“Follow basic coding conventions, while making good use of comments and white spaces” (Checklist 2

#128 The reliability of replications: a study in computational reproductions · injunctive

“truly elegant code should be well-structured, well-documented and comprehensible for researchers who do not use the software” (p. 19)

#131 Guide for Accelerating Computational Reproducibility in the Social Sciences · tacit

Improve documentation by adding comments to the code.