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
| File | Purpose |
|---|---|
README.md | What the project is and how to run it |
LICENSE | The terms others may use your code under; without one, default copyright applies |
.gitignore | Keeps build output, dependencies and secrets out of version control |
.editorconfig | Shared indentation and line-ending rules that most editors respect |
.env.example | Names of the settings the app needs, with fake values |
| Manifest | package.json, pyproject.toml, go.mod or similar: name, version, dependencies |
| Lock file | Exact 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
- Run
git initand create the.gitignorebefore anything else, so dependency folders are never committed. - Add the manifest and install one dependency to create the lock file.
- Write a hello-world entry point and one passing test, so the test command works from day one.
- Add a linter and a formatter, and run them once over the empty project.
- Write a three-line README: one sentence on purpose, the install command, the run command.
- Choose a licence, or state clearly that the code is private.
- 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.exampleis committed. Use obvious placeholders. - Deep nesting early.
src/core/lib/utils/helpershides 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.