FIT9131 Coding Guideline
本页目录· 13 条
英文版
3.4.1 Coding standards
When writing large and complex programs, it is vital for programmers to adhere to a set of standards for writing the code. Adherence to this standard ensures that the overall program quality is high, and it allows other programmers to quickly recognise and understand the written code.
While it may seem pedantic to focus on not having a single extra space when writing code, more often than not the overall quality of a system is assumed based on the attention to detail by the programmers.
Please remember there are a number of aspects that affect the overall quality of program code. For now, however, we will focus on some conventions to follow when writing the code. We will cover other aspects later in the unit.
The following FIT9131 Coding Standards list the coding conventions we will follow when programming in this unit. These are based on the Program Style Guide from Objects First with Java by Barnes and Kölling, 6th Edition.
You will practice applying these coding standards in your Workshop in week 3.
FIT9131 Coding Standards
1. Naming
1.1 Use descriptive names for all identifiers (names of variables, methods, and classes).
1.2 Avoid abbreviations and ambiguity. For example, use number instead of num or no.
1.3 Use camel case for names with multiple words to increase readability. With camel case the second and subsequent words begin with a capital letter. For example, numberOfItems.
See below further guidelines for specific naming of variables, methods, and classes.
2. Operators:
2.1 When defining expressions using operators, there should be a single space before and after the operator for the following types of operators: arithmetic (+, -, *, /, %), relational (>, >=, <, <=, ==, !=), logical (&&, ||, !), conditional ( ? :), assignment (=), and compound assignment (= += -= *= /= %=).
3. Variables:
3.1 Fields must only be initialised in the constructor, unless they are static or final.
3.2 Local variables must be initialised when they are declared.
3.3 The use of public fields must be justified.
3.4 Variable names must use camel casing with the first character always in lowercase.
3.5 Variable names must not contain an underscore ( _ ) (except final variables).
3.6 Final variables must be in all capital letters and must use an underscore to split up multiple words in the name.
4. Methods:
4.1 Methods must have exactly one blank line between each method, and between the start and end of the class's delimiter ({ })'s.
4.2 Method names must be or contain action verbs. Names should be descriptive and convey a high level idea of the purpose of the method.
4.3 Method names must use camel casing with the first character always lowercase.
4.4 Methods must be sorted alphabetically (except constructors, which always appear first).
4.5 Simple mutator methods should be named setSomething and accessor methods should be named getSomething. Accessor methods with boolean return values are often called isSomething.
5. Classes:
5.1 Class names must be nouns and must be singular.
5.2 Class names must follow camel casing with the first character always uppercase.
5.3 Each file must only contain one class definition.
5.4 A complete class template must include:
- one default constructor
- at least one non-default constructor (if the class has fields)
- accessors for each field
- mutators for each field
- a display/toString method.
5.5 The components of a class must be defined in the following order: fields, constructors, methods
6. Brackets and indentation:
6.1 All code within a specific block must have exactly one indent. One indent is equal to one tab or four spaces.
6.2 The placement of { }'s to start and end a block must appear on their own line. Opening braces ({) especially should not be placed on the same line as the header.
7. Code:
7.1 Access modifiers are not optional and must be explicitly defined for methods and fields.
7.2 The maximum code line length should be 80 characters. To prevent code going off the screen, consider breaking the code across multiple lines.
7.3 Each statement should be on a separate line.
7.4 Any code that has been copied from another source must be otherwise appropriately credited.
8. Documentation:
8.1 Every class should have a comment at the top, which should include a general description of the class, the author's name and version number.
8.2 Every person who has contributed to a class must be named as an author or must be otherwise appropriately credited.
8.3 Every method should have a comment at the top with a general description of the method.
8.4 Inline comments should only be included where they are necessary to explain a key concept. Excessive inline comments must be avoided as they affect code readability.
The above is a finite list of conventions that must be followed when programming in this unit. Failing to adhere to these standards will generally cost marks on all assessed submissions after this module.
中文翻译版
FIT9131 编码标准
1. 命名（Naming）
1.1 所有标识符（变量、方法和类的名称）必须使用有意义的名称。
1.2 避免使用缩写和模糊的命名。例如，应使用 number 而不是 num 或 no。
1.3 多个单词组成的名称应使用 驼峰命名法（camel case），以提高可读性。即，从第二个单词开始，每个单词的首字母应大写，例如：numberOfItems。
下方提供了针对变量、方法和类的具体命名规范。
2. 运算符（Operators）
2.1 在使用运算符定义表达式时，以下类型的运算符前后必须各有一个空格：
- 算术运算符：+, , , /, %
- 关系运算符：>, >=, <, <=, ==, !=
- 逻辑运算符：&&, ||, !
- 条件运算符：? :
- 赋值运算符：=
- 复合赋值运算符：**+=, -=, =, /=, %=
3. 变量（Variables）
3.1 字段（fields） 只能在构造函数（constructor）中初始化，除非它们是 static 或 final。
3.2 局部变量（local variables） 必须在声明时初始化。
3.3 使用 public 字段必须有合理的理由。
3.4 变量名称 必须遵循驼峰命名法（camel case），并且首字母应小写。
3.5 变量名称 不得 包含下划线 _（final 变量除外）。
3.6 final 变量名称必须全部使用大写字母，并使用下划线 _ 分隔多个单词。
4. 方法（Methods）
4.1 方法之间必须有且仅有 一行 空行，在类的起始 { 和结束 } 之间也必须有空行。
4.2 方法名称必须包含或是 动词，名称应具有描述性，并能清晰表达方法的功能。
4.3 方法名称 必须使用驼峰命名法，且首字母小写。
4.4 方法必须按字母顺序排列（构造方法 constructor 除外，构造方法应始终放在最前面）。
4.5 简单的 修改器方法（mutator methods） 应命名为 setSomething，访问器方法（accessor methods）应命名为 getSomething。返回值为 boolean 类型的访问器方法通常命名为 isSomething。
5. 类（Classes）
5.1 类名 必须是 名词，且必须为 单数形式。
5.2 类名 必须遵循驼峰命名法（camel case），且首字母大写。
5.3 每个文件只能包含一个类定义。
5.4 完整的类模板 必须包括：
- 一个默认构造方法（default constructor）
- 至少一个非默认构造方法（如果类有字段）
- 每个字段的访问器（accessor）
- 每个字段的修改器（mutator）
- 一个
display或toString方法
5.5 类的组成部分必须按照以下顺序定义：
- 字段（Fields）
- 构造方法（Constructors）
- 方法（Methods）
6. 括号与缩进（Brackets and Indentation）
6.1 所有代码块内的代码必须缩进一级。一个缩进单位等于 一个 Tab 键或四个空格。
6.2 大括号 {} 的位置：
- 必须 独占一行
{不能和方法声明在同一行
7. 代码（Code）
7.1 访问修饰符（Access Modifiers） 必须明确指定，不得省略。
7.2 单行代码最大长度为 80 个字符。如果一行代码过长，建议换行。
7.3 每条语句必须独占一行。
7.4 任何从其他来源复制的代码 必须适当标明来源。
8. 文档注释（Documentation）
8.1 每个类的顶部 必须有一条注释，包含以下信息：
- 该类的简介
- 作者姓名
- 版本号
8.2 所有对类有贡献的人 必须在作者信息中注明，或在适当位置标明贡献。
8.3 每个方法的顶部 必须有一条注释，包含该方法的概述。
8.4 内联注释（Inline Comments） 仅应在必要时使用，以解释关键概念。避免过多的内联注释，以免影响代码可读性。
以上列出的是 必须遵守的编码约定。如果不遵守这些标准，在本单元的作业评分中将会被扣分。