java style --对编写java代码规范性的相关指导建议

 

一、General Principle

1.adhere to the style of original

2.adhere to the principle of least astonishment

3.do it right the first time

4.document any deviations

---

二、Formatting conventions

5.indent nested code

6.break up long lines

7.include white space

8.do not use 'hard' tables

---

三、Naming Conventions

9.use meaningful names

10.use familiar names

11.question excessively long names

12.join the vowel generation

13.capitalize only the first letter in acronyms

14.do not use the names that differ only in case

Package Names

15.use the reverse,lowercase form of your orgnization's Internet domain name as the root qualifier for your package names.

16.use the single,lowercase word as the root name of each package.

17.use the same name of a new version of a package,but only if the new version is still binary compatible with the previous version , otherwise , use a new name.

Type Names

18.capitalize the first letter of each word that appear in a class or interface name.

19.use nouns when naming classes.

20.pluralize the names of classes that group related attributes,static services , or constants.

Interface Names

21.use nouns or adjectives when naming interfaces.

Method Names

22.use lowercase for the first word and capitalize only the first letter of each subsequent word that appear in a method name.

23.naming verbs when naming methods.

24.follow the JavaBeans conventions for naming property accessor methods.

variable names

25.use lowercase ofr the first word and capitalize only the first letter of each subsequent word that appear in a variable name.

26.use nouns to name variables.

27.pluralize the names of collection references.

28.establish and use a set of standard names for trivial 'throwaway' variables.

Field Names

29.qualify field names by "this" to distinguish them from local variable.

Parameter Names

30.when a constructor or a set method assigns a parameter to a field, give that parameter the same name as the field.

Constants Names

31.use uppercase letters for each word and separate each pair of words with an underscore when naming constants.

---

三、Document Conventions

32.write documentation for those who must use your code and those who must maintain your code.

33.keep comments and code in sync.

34.use the active voice and omit needless words.

35.use documentation comments to describe the programming interface.

36.use standard comments to hide code without removing it.

37.use one-line comments to explain implementation details.

Documentation Comments

38.describe the programming interface before you write the code.

39.document the public , protected , package and private members.

40.provide a summary description and overview for each package.

41.provide a summary description and overview for each application or group of packages.

Comment Style

42.use a single consistent format and organization for all documentation comments.

43.wrap keywords , identifiers ,and constants with <//code>...<//code> tags.

44.wrap code with <//pre>...<//pre> tags.

45.consider marking the first occurrence of an identifier with a {@link } tag.

46.establish and use a fixed ordering for javadoc tags.

47.write the third-person narrative form

48.write summary description that stand alone.

49.omit the subject in summary descriptions of action and services.

50.omit the subject and verb in summary of things.

51.use 'this' rather than 'the' when to reference instances of the current class.

52.do not add parentheses to a method or constructor names unless you want to specify a particular signature.

Comment Content

53.provide a summary description for each class, interface , field , and method.

54.fully describe the signature of each method.

55.include examples.

56.document preconditions , postconditions , and invariant conditions.

57.document known defects and deficiencies.

58.document synchronization semantic.

Internal Comments

59.add internal comments only if they aid others understand ing your code.

60.describe why the code is doing what it does , not what it is doing.

61.avoid the end-line comments.

62.explain local variable declaration with an end-line comment.

63.establish and use a set of keywords to flag unresolved problem.

64.label closing braces in highly nested control structures.

65.add a full-through comment between two case labels , if no break statement seprates those labels.

66.label empty statements.

---

Programming Conventions

67.consider declaring classes representing fundamental data types as final.

68.build concrete types from native type and other concrete types.

69.try to define small classes and small methods.

70.define subclasses so they may be used anywhere their superclasses may be used.

71.make all fields private.

72.use polymorphism instead of instanceof

Type safely

73.wrap general-purpose classes that operator on java.lang.object to provide static type checking.

74.encapsulate enumeration as class.