Overview

This web module serves as the complete (when supporting style guides are included) definition of the Deep Dive Coding Java + Android Bootcamp standards for Java and SQL source code, as well as pseudocode files or fragments, XML documents, and JSON values. A Java, SQL, XML, JSON, or pseudocode source file, document, or fragment may be described as being “in DDC Java + Android Bootcamp Style” if and only if it adheres to the rules stated or referenced in this module.

Purpose

Coding conventions are for your benefit, and the benefit of other programmers working with you.

It might surprise you to learn that the Java compiler doesn’t care about leading whitespace (indentation) in your code, or about the amount of vertical whitespace between methods, or horizontal whitespace before and after commas, etc.¹ With some important exceptions, it doesn’t even care about how you name your classes, interfaces, variables, and methods. However, your eyes and brain—and those of your teammates—do care a great deal about all of these. In particular, our brains care a lot about consistency and visually predictable structure.

XKCD: “Code Quality”, licensed under a Creative Commons Attribution-NonCommercial 2.5 License.

No set of naming and formatting conventions suits every developer, language, organization, or project perfectly, but adopting a reasonable set of conventions as an organization facilitates our working together more effectively and efficiently. In the Deep Dive Coding Java + Android bootcamp, we’ve formulated this style guide, based in large part on the Google style guides—the Java portion of which is based in turn on Oracle’s (originally Sun’s) Code Conventions for the Java™ Programming Language.

Usage

Many of the rules stated or referenced here are applied by the IntelliJ IDEA Code/Reformat Code command—some by default, and more with the IntelliJ scheme included in the Google Style Guide repository installed. However, not all rules stated here can be enforced in this fashion: in particular, Code/Reformat Code does not enforce naming or general structure/sequence conventions (some of the latter are enforced by the Code/Rearrange Code command), and it does not remove many instances of extra vertical whitespace. In any given instance where a stated rule is not applied by this command, that does not excuse the student from following that rule. Similarly, if some example or starter code provided by an instructor (or anyone else) is not conformant with this style guide, that does not excuse the student from the conformance requirement. (Note also that while IntelliJ IDEA, along with a number of other IDEs, provides some support for editing and previewing Markdown content, none of them will perform any special formatting of pseudocode, even when it is written in Markdown.)

Most of the rules in this style guide are strict but not all-encompassing; that is, for any non-trivial processing task, there’s a wide range of code expressions that complete the given task and still conform to the rules of this style guide.

Note: Words and phrases like “must”, “must not”, “do”, “do not”, etc., written in bold type (excluding the headings, which are also in bold type), indicate strict rules of this style guide. Italicized words and phrases indicate recommendations or qualifications/clarifications of rules.

Site contents

• Introduction: Why are coding conventions important?
• Pseudocode
  • Overview: Expressing algorithms in unambiguous, programming-language-agnostic terms.
  • Elements: Practices to rely on (and avoid) in pseudocode.
  • Example: Markdown with embedded LaTeX.
• Java
  • Overview: Java source code conventions.
  • Source files: Structuring, ordering, and formatting Java source code files.
  • Coding Practices: Naming and other practices in Java source code.
  • Javadoc: Standards for documentation comments.
• SQL
  • Overview: ORM-oriented SQL conventions for Java projects.
  • Files: ORM-oriented SQL conventions for Java projects.
  • Elements: Casing, naming, and data type guidelines for database objects.
  • Formatting: Guidelines for SQL statements in .sql files and embedded in Java annotations.
  • General Practices: Guidelines for non-ORM-generated SQL code.
• JSON: Conventions for JSON included as resources in Java projects.
• XML: Guidelines for XML schemas and documents in Java projects.
• Additional Resources: Documentation and tools.

1. This is not just true of the Java compiler, but also the interpreters and compilers for JavaScript, C, C#, C++, and many other languages. However, an instructive contrast is found in the Python language: It has less requirement for boilerplate (especially grouping constructs) than Java, C, JavaScript, etc. do—but there’s a trade-off: In Python, indentation is semantically significant, with the number of leading whitespace characters before a statement determining its indentation level, and thus to which statement (if any) it is subordinate. This can cause problems—including runtime crashes or other unexpected behavior—for programmers learning Python, if they don’t use consistent indentation. ↩