3.3 Software Implementation — Coding, Standards & Documentation

What is implementation?

Implementation (coding) is the phase that turns design into executable source code. Despite being the most visible phase, it is not the most time-consuming — typically 20–30% of total project effort. Design, testing, and maintenance together dwarf coding.

A successful implementation phase requires:

1. Good coding style and standards
2. Structured coding techniques to control complexity
3. Code documentation so future maintainers can understand the code
4. Unit testing alongside coding
5. Configuration management of the code base

---

Structured Coding

Structured coding (Edsger Dijkstra, 1968 — "GoTo Statement Considered Harmful") restricts control flow to three basic constructs. The Böhm-Jacopini theorem proves these three are sufficient:

Plus structured procedures and functions.

The 7 rules of structured programming

1. Use only sequence, selection, iteration
2. Each construct has one entry and one exit
3. Avoid goto statements
4. Use meaningful variable names
5. Keep functions short (≤ 1 screen, ~30 lines is a common rule)
6. Use indentation to show structure
7. Comment intent, not mechanics

Why structured coding matters

Without these constraints, control flow becomes "spaghetti code" — paths cross, jumps go everywhere, and a small change can break far-away parts. Cyclomatic complexity goes up; testability goes down.

---

Coding Style

Coding style is the set of conventions a team agrees on for writing code that humans can read. Style is for readers, not authors.

Naming conventions

Naming guidelines

• Meaningful, not clever — accountBalance not ab or x
• Pronounceable — genymdhms is bad; generationTimestamp is good
• Searchable — short names like i only for tiny loop counters
• One concept, one word — don't mix fetch, get, retrieve for the same idea
• Avoid encodings — Hungarian notation (strName, iCount) is dated

Formatting

• Consistent indentation (4 spaces or 2 spaces — pick one)
• Brace style: K&R vs Allman — pick one and stick
• Line length: typically ≤ 100 characters
• Blank lines to separate logical chunks
• One statement per line

Comments

• Comment why, not what. Code shows what; comments explain why.
• // Loop through students — useless.
• // Re-sort each iteration because earlier scoring may change rank — useful.
• Avoid commented-out code; delete it. Version control remembers.
• Keep comments synchronised with code — stale comments are worse than missing ones.

---

Coding Standards — examples

Different languages and organisations adopt different standards. Common ones:

Most companies adopt one and enforce it via linters (e.g. ESLint, Pylint, Checkstyle, SonarQube).

---

Standards and Guidelines (IPU specifics)

The IPU textbook distinguishes:

Standards typically cover: naming, formatting, structure, documentation, file organisation. Guidelines cover: best practices, design patterns, error-handling preferences.

---

Code Documentation — types

                  Documentation
                  /            \
            Internal           External
           (within code)      (separate docs)
              │                    │
       ┌──────┴──────┐      ┌──────┴────────┐
       │             │      │               │
  Header     Inline    User Guide    API / Tech Docs
  comments   comments

Internal documentation

File / class headers describe the unit's purpose:

/**
 * StudentRegistration handles all student-record creation,
 * update and deletion operations for the BCA admissions system.
 *
 * @author     A. Sharma
 * @since      2024-09
 * @lastModified  2025-02
 */
public class StudentRegistration { ... }

Function headers describe parameters, return values, side effects:

/**
 * Calculates simple interest.
 *
 * @param principal  Principal amount in INR; must be > 0
 * @param rate       Annual rate as a decimal (e.g. 0.08 for 8%)
 * @param years      Time in years; must be > 0
 * @return           Interest in INR
 * @throws           IllegalArgumentException on invalid input
 */
public double simpleInterest(double principal, double rate, int years) { ... }

External documentation

Documentation tools

---

Code Walkthroughs and Reviews

The implementation phase is also when peer reviews happen — these are quality activities applied to source code rather than design.

Modern equivalents include pull-request reviews in GitHub/GitLab — the same activity, automated.

---

Code Quality Tools (modern context)

Most modern teams enforce these in CI (continuous integration) — code that fails a check cannot be merged.

---

Unit Testing alongside coding

Unit testing is part of implementation, not a separate phase. Best practices:

• Write tests for each public function
• Use Test-Driven Development (TDD) — write failing test first
• Aim for ~80% code coverage (100% is rarely worth the cost)
• Use frameworks: JUnit (Java), PyTest (Python), Jest (JS), NUnit (.NET)

Detailed testing covered in Unit IV.

---

Key Terms — Lesson 3.3

The vocabulary below covers the implementation phase — structured coding, style, documentation, and the modern tooling that surrounds code today.

Implementation / Coding Phase — The SDLC phase that converts the design (SDD) into executable source code plus unit tests, supporting build scripts, configuration files, and code-level documentation. Despite being the most visible phase, coding is only 20–30% of total project effort; design, testing, and maintenance together dominate.

Structured Programming — A programming discipline (Dijkstra, 1968) that restricts control flow to three basic constructs — sequence, selection, iteration — and forbids unrestricted GOTOs. The Böhm-Jacopini theorem proves these three constructs are sufficient to express any computable function.

Sequence / Selection / Iteration — The three structured-programming constructs. Sequence executes statements one after another. Selection chooses between paths (if/else, switch). Iteration repeats (for, while). Each has one entry point and one exit point, which is what makes structured code analysable.

"GoTo Statement Considered Harmful" — Edsger Dijkstra's seminal 1968 letter to CACM arguing that the unrestricted GOTO statement makes programs impossible to reason about because control can jump anywhere. The letter launched structured programming and remains one of the most cited papers in computing.

Spaghetti Code — Code where control flow has become tangled — many GOTOs, deeply nested conditionals, methods that loop into and out of each other. Spaghetti code has high cyclomatic complexity, low cohesion, high coupling, and is essentially unmaintainable.

Coding Style — The set of conventions a team agrees on for writing code that humans can read — naming, formatting, indentation, comment style, file layout. Style is for readers, not authors. The choice of style matters less than the consistency of style within a codebase.

Naming Conventions — Rules for how identifiers (variables, functions, classes, constants) are named. Common conventions: camelCase (Java, JavaScript), snake_case (Python, Ruby), PascalCase for classes, UPPER_SNAKE_CASE for constants. Good names are meaningful, pronounceable, searchable, and consistent.

PEP 8 — The Python Enhancement Proposal #8, the de-facto Python style guide. Defines naming conventions (snake_case for functions, PascalCase for classes), indentation (4 spaces), maximum line length (79 chars), import order, and a hundred other conventions. Most Python code in the world conforms (or aspires) to PEP 8.

Coding Standards vs Guidelines — A standard is mandatory and enforced; deviation requires a documented exception. A guideline is advisory; deviation requires only a defensible reason. Most organisations have a hierarchy: industry standards (PEP 8, MISRA-C), corporate standards (must follow), team guidelines (should follow).

Hungarian Notation — A naming convention popular in Microsoft 1980s–90s code where the type or scope of a variable is encoded as a prefix — strName, iCount, m_Field, g_Global. Hungarian notation is considered outdated; modern IDEs show types in tooltips, making the encoding redundant.

Linter — A static-analysis tool that scans source code and flags style violations and bug patterns — unused variables, missing semicolons, dangerous comparisons, undefined references. ESLint (JS), Pylint (Python), Checkstyle (Java), SonarQube (multi-language) are the dominant linters.

Formatter — A tool that automatically reformats source code to a configured style — Prettier (JS/TS/CSS), Black (Python), gofmt (Go), rustfmt (Rust). Modern teams run formatters in pre-commit hooks so style debates never reach pull-request reviews.

Static Analyser — A tool that goes deeper than a linter — performs flow analysis to detect potential bugs (null-pointer dereferences, race conditions, security issues) before code runs. SonarQube, Coverity, Veracode, Snyk Code are leading static analysers.

Documentation — All written material that explains the software to its readers — users, administrators, developers, maintainers. Distinguished as internal documentation (comments and docstrings inside the code) and external documentation (separate documents like user manuals and API guides).

Internal Documentation — Comments, docstrings, and file/class/function headers that live inside the source code. Internal documentation is the closest to the code and the most likely to stay accurate during maintenance.

Docstring — A specific kind of internal documentation in many languages (Python, Java's Javadoc, JavaScript's JSDoc, C#'s XML doc) — a structured comment immediately above a function, class, or module that describes purpose, parameters, return value, exceptions, and examples. Docstrings are read by both humans and tools (auto-generated API docs).

Javadoc / Doxygen / Sphinx / JSDoc — Documentation-generation tools that read structured comments and produce browsable HTML/PDF documentation. Javadoc for Java, Doxygen for C/C++ (and many others), Sphinx for Python (using reStructuredText or Markdown), JSDoc for JavaScript. Swagger / OpenAPI plays the equivalent role for REST APIs.

External Documentation — Documents that live separately from the source code — user manual, installation guide, API documentation, technical/architecture manual, operations runbook. External docs target audiences who do not read source code.

User Manual — End-user-facing documentation explaining how to use the product. Modern user manuals are increasingly interactive help, onboarding tours, and embedded tutorials rather than 200-page PDFs.

Operations Manual / Runbook — Documentation for the on-call/DevOps team describing how to deploy, monitor, troubleshoot, and recover the production system. Includes runbook steps for common incidents.

Code Review / Pull Request (PR) Review — The practice of having one or more peers examine code changes before they merge into the main branch. Modern code review is centred on the pull request (PR) on GitHub/GitLab — the same activity as Fagan inspection, but lighter-weight and integrated with version control.

Clean Code — Robert C. Martin's 2008 book and the term has come to describe code written for human readability — meaningful names, small functions doing one thing, minimal comments, consistent style, defensible structure. Martin's headline rule: code is read 10× more than it is written.

Principle of Least Astonishment (POLA) — A design principle: code should behave the way a reasonable reader would expect. Surprising behaviour, even when technically correct, is bad code. Naming, error handling, and side effects should all be predictable.

Unit Test — A test of a single small unit (a function, method, or class) in isolation, usually written by the developer who wrote the code being tested. Unit tests run fast (milliseconds), are executed every commit, and form the safety net that makes refactoring possible.

Test Coverage — The percentage of code executed by the test suite — line coverage (which source lines run), branch coverage (which conditional branches are taken), or path coverage. ~80% line coverage is a common industry target; 100% is rarely worth the cost.

JUnit / PyTest / Jest / NUnit — The dominant unit-testing frameworks for Java, Python, JavaScript/TypeScript, and .NET respectively. Each provides a standard way to declare tests, assertions, fixtures, and lifecycle hooks.

Test-Driven Development (TDD) — Kent Beck's discipline of writing a failing test first, then writing the minimum code to make it pass, then refactoring — the red-green-refactor cycle. TDD produces tightly-tested code, pressures simple designs, and ensures every line of production code has a corresponding test.

Continuous Integration (CI) — The practice of automatically building and testing every commit to the main branch using a CI pipeline (GitHub Actions, GitLab CI, Jenkins, CircleCI). Linters, formatters, type-checkers, unit tests, and security scanners all run in CI; failing code cannot be merged.

Pre-Commit Hook — A script that runs before a commit is allowed to be created — typically formats code, runs linters, and rejects commits that fail. Tools: husky (JS), pre-commit (Python framework, language-agnostic), Git's native hooks directory.

---

Study deep

1. Code is read 10× more than it's written. Robert C. Martin's Clean Code puts the readability ratio at 10:1. Every minute spent making code readable saves 10 minutes of future reading.

1. Style consistency matters more than style choice. Tabs vs spaces is religious; consistency is engineering. Pick a style and enforce it. The disagreement that hurts is not between styles, but within a codebase.

1. Documentation rots. Code changes but docs don't. The only sustainable approach is to put documentation as close to code as possible — header comments, generated API docs, executable specifications (BDD), and tests that double as examples.

1. The 'principle of least astonishment'. Code should behave as a reader would expect. Surprising behaviour — even if technically correct — is bad code. Naming, error handling, and method behaviour should all be predictable.

1. Tools won't save bad practices. Linters enforce surface-level style, but only humans can judge whether a function has a clear purpose or whether a name truly reflects intent. Combine automated checks with human reviews.

PYQ pattern: "What are coding standards? List the importance of coding style and documentation." — Define standards vs guidelines; list 4–5 naming/formatting/commenting rules; describe internal vs external documentation; mention tools like Javadoc, Doxygen, Sphinx.