SpunkArt
Command line and project setup

How to scaffold a new code project

Scaffolding means creating the empty skeleton of a project before real work starts: folders, config files, a README and a first commit. Ten minutes spent here saves hours of reorganising later.

Generators versus doing it by hand

Most frameworks ship a generator command that writes a starter project for you. Use it when you have picked that framework; it knows the conventions better than any blank folder. Building a skeleton by hand still pays off for small libraries, scripts and services, and it teaches you what each generated file is for, so you can delete what you do not need.

A layout that scales

project/
  src/            source code you write
  tests/          automated tests, mirroring src/
  scripts/        one-off helpers: seed data, release, cleanup
  docs/           longer documentation and decisions
  .github/        CI workflows and issue templates
  README.md
  LICENSE
  .gitignore
  .editorconfig
  .env.example

Three ideas sit behind this shape. Code you ship is kept apart from code that supports it. Tests sit where you will look for them. And anything a new contributor must read first is at the top level. Language communities vary: Go puts commands under cmd/, Rust uses src/main.rs and Cargo.toml, and many Python projects use a src/package_name/ layout. Follow the convention of your language before your own taste.

The starter files and why each exists

FilePurpose
README.mdWhat the project is and how to run it
LICENSEThe terms others may use your code under; without one, default copyright applies
.gitignoreKeeps build output, dependencies and secrets out of version control
.editorconfigShared indentation and line-ending rules that most editors respect
.env.exampleNames of the settings the app needs, with fake values
Manifestpackage.json, pyproject.toml, go.mod or similar: name, version, dependencies
Lock fileExact dependency versions, created by the package manager; commit it

A minimal .editorconfig

root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.md]
trim_trailing_whitespace = false

Markdown is the exception because two trailing spaces there create a line break.

Give every task one command

A newcomer should be able to set up, run and test the project without reading the source. Whatever the language, expose the same verbs: install, dev, test, lint, build. In JavaScript they go in the scripts section of package.json; elsewhere a short Makefile works:

.PHONY: test lint
test:
	python -m pytest
lint:
	ruff check src tests

Make requires a real tab character at the start of each command line, not spaces.

First-commit checklist

  1. Run git init and create the .gitignore before anything else, so dependency folders are never committed.
  2. Add the manifest and install one dependency to create the lock file.
  3. Write a hello-world entry point and one passing test, so the test command works from day one.
  4. Add a linter and a formatter, and run them once over the empty project.
  5. Write a three-line README: one sentence on purpose, the install command, the run command.
  6. Choose a licence, or state clearly that the code is private.
  7. Commit, then add a CI workflow that runs the tests on every push.

Common mistakes

  • Over-scaffolding. Empty folders for features you may never build make the project look bigger and harder to read. Add structure when code arrives.
  • Real secrets in the example file. .env.example is committed. Use obvious placeholders.
  • Deep nesting early. src/core/lib/utils/helpers hides code. Stay flat until a folder holds many files.

Questions

Should tests live next to the code instead?

Both styles are common. Co-located tests such as button.test.ts beside button.ts are popular in front-end work. Pick one and stay consistent.

Which licence should I pick?

That depends on what you want others to be able to do. Permissive licences allow almost any use; copyleft licences require shared changes. Read the licence text before you choose.