Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 50 ยท Quality, Testing and Delivery

Coding Standards and Software Documentation

Learn why teams adopt coding standards and guidelines, what good ones contain, and how to write useful software documentation for users, developers and operators.

Code is read far more often than it is written. Two practices make the reading easier for the next person (who is often you in six months): coding standards and guidelines, which make the code itself consistent, and software documentation, which explains what the code cannot say on its own.

Coding standards versus guidelines

A coding standard is a set of rules a team agrees to follow and can often check automatically: "use four spaces", "class names are PascalCase", "no function longer than 50 lines". A coding guideline is advice that needs judgment: "prefer composition to inheritance", "write comments that explain why". Standards are enforced by tools; guidelines are applied in code review.

Why teams adopt them

  • Uniform appearance: any file looks like it was written by one person, so reviews focus on logic, not style.
  • Readability and maintainability: consistent code is easier to change (see maintenance).
  • Fewer bugs: rules against known traps (unchecked return values, unused variables, implicit conversions) prevent classes of defects.
  • Faster onboarding and less arguing about taste.
  • Reuse: consistent interfaces and naming make modules easier to combine.

The cost is some up-front agreement and the risk of rules nobody understands. Good standards are short, explained, and checked by a formatter or linter rather than by nagging.

What a standard usually covers

Area Typical rules
Naming Descriptive names, one convention (camelCase, snake_case, PascalCase), constants in UPPER_CASE
Layout Indentation (spaces or tabs, one choice), line length, braces, blank lines
Comments Explain intent and non-obvious decisions, not what the code obviously does
Functions Small, one purpose, few parameters, one level of abstraction
Variables Declared close to first use, narrow scope, limited use of globals
Error handling No silently swallowed errors, specific exception types, clear messages
Files One main class or concern per file, header with purpose
Security Validate input, never hard-code secrets, parameterized queries

Two classic rules deserve a closer look.

Limit global data. Globals can be changed from anywhere, so any bug can hide anywhere. Keep data local, pass it as arguments, and when you must share state, expose it through a small, controlled interface.

Use each identifier for one purpose. A variable named temp that holds a count, then a name, then a flag, is a bug waiting to happen. Reusing names to "save memory" is a false economy on modern machines.

Some teams add naming prefixes by data scope (for example g_ for globals, m_ for members, CONST_ for constants). Modern editors show scope anyway, so many teams now rely on naming by meaning plus tooling instead.

JS Before and after the guidelines

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Putting standards into practice

  1. Start from a published style guide for your language instead of inventing one.
  2. Automate: a formatter fixes layout, a linter flags risky patterns, and both run in continuous integration.
  3. Keep the human rules (naming meaning, design) in the review checklist.
  4. Revisit the rules when they cause friction; allow documented exceptions.
JS A tiny linter

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Software documentation

Documentation is everything written about the software, apart from the code. It carries knowledge that people forget and new team members need.

Kinds of documentation

Audience Documents
End users User guide, tutorials, FAQ, release notes, in-app help
Developers Architecture overview, API reference, decision records, code comments, setup guide
Operators Runbooks, deployment and monitoring guides, backup and recovery steps
Analysts and testers SRS, UML models, test plans and reports
Managers Project plan, schedule, risk register, status reports

Principles of good documentation

  • Write for a specific reader and state who that is.
  • Avoid unnecessary repetition. Duplicated facts drift apart. Say it once and link to it.
  • Avoid ambiguity. Use precise terms, define jargon once, give examples, and keep a glossary.
  • Record the rationale. Why was this option chosen over the alternatives? The code shows what; only documentation can show why.
  • Keep it current. Out-of-date documentation is worse than none. Store it next to the code, update it in the same change, and review it.
  • Keep it readable. Short sentences and plain words; a low fog index is a good target.

Documentation that lives in the repository (a README, docs folders, doc comments that generate an API site) tends to stay fresher than a wiki nobody owns.

Advantages and disadvantages

Documentation preserves knowledge, makes onboarding and handover easier, supports maintenance and audits, and lets teams work without constant interruptions. It also costs time to write, becomes stale, and heavy documents can slow agile teams. The usual answer is "just enough": document what is stable and expensive to rediscover, and prefer working software and automated tests for the rest.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the difference between a coding standard and a coding guideline?

    Standards can usually be enforced automatically. Guidelines are best practice that people apply with judgment.
  2. 2. Why should an identifier be used for one purpose only?

    A name should say what the value is. Reusing it for unrelated values hides that meaning.
  3. 3. Which is the best use of a code comment?

    Code shows what happens; comments and documentation should add the intent and rationale.
  4. 4. What is the main danger of outdated documentation?

    People trust what is written. Wrong documentation leads to wrong decisions.

Summary

  • Standards are enforceable rules; guidelines are judgment-based advice. Both make code consistent and maintainable.
  • Cover naming, layout, comments, functions, variables, error handling and security; limit globals and give each identifier one purpose.
  • Automate with formatters and linters in CI; keep design questions for code review.
  • Documentation serves users, developers, operators, testers and managers; write for a reader, avoid repetition and ambiguity, record rationale and keep it current.

Next: Version control and CI.