AEP-0140 Linter Rules

Field names- Abbreviations

Field names: Abbreviations

This rule enforces that field names use common abbreviations, as mandated in AEP-140.

Details

This rule checks every descriptor in the proto and complains if the long form of any of the following words are used instead of the abbreviation:

configuration
identifier
information
specification
statistics

Examples

Single word method

Incorrect code for this rule:

// Incorrect.
message Book {
  string name = 1;
  string identifier = 2;  // Should be `id`.
}

Correct code for this rule:

// Correct.
message Book {
  string name = 1;
  string id = 2;
}

Disabling

If you need to violate this rule, use a leading comment above the method. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0140::abbreviations=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  string name = 1;
  string identifier = 2;  // Should be `id`.
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

Base64 fields

This rule tries to enforce that base64 fields use the bytes type, as mandated by AEP-140.

Details

This rule checks the comments over each field, and if “base64” is mentioned, and yet the field is a string, it suggests using bytes instead.

Examples

Single word method

Incorrect code for this rule:

// Incorrect.
message Book {
  string name = 1;

  // The base64-encoded checksum.
  string checksum = 2;  // Should be bytes.
}

Correct code for this rule:

// Correct.
message Book {
  string name = 1;

  // The base64-encoded checksum.
  bytes checksum = 2;
}

Disabling

If you need to violate this rule, use a leading comment above the method. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0140::base64=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  string name = 1;

  // The base64-encoded checksum
  string checksum = 2;
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

Field names- Lower Snake Case

Field names: Lower Snake Case

This rule enforces that field names use snake_case, as mandated in AEP-140.

Details

This rule checks every field in the proto and complains if the field name contains a capital letter.

Examples

Single word method

Incorrect code for this rule:

// Incorrect.
message Book {
  string name = 1;
  int32 pageCount = 2;  // Should be `page_count`.
}

Correct code for this rule:

// Correct.
message Book {
  string name = 1;
  int32 page_count = 2;
}

Disabling

If you need to violate this rule, use a leading comment above the method. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0140::lower-snake=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  string name = 1;
  string pageCount = 2;
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

Field names- Numbers

Field names: Numbers

This rule enforces that field names do not begin any word in the field with a number, as mandated in AEP-140.

Details

This rule checks every field in the proto and complains if any individual word begins with a number. It treats the underscore (_) character as the only word separator for this purpose.

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  string name = 1;
  int32 review_90th_percentile_stars = 2;
}

Correct code for this rule:

The correct code here is likely to vary based on the situation. This may be fixed by spelling out the number:

// Correct.
message Book {
  string name = 1;
  int32 review_ninetieth_percentile_stars = 2;
}

Many cases we see involving numbers like this may be better designed with a map:

// Correct.
message Book {
  string name = 1;
  map<int32, int32> review_stars_per_percentile = 2;
}

Disabling

If you need to violate this rule, use a leading comment above the method. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0140::numbers=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  string name = 1;
  int32 review_90th_percentile_stars = 2;
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

Field names- Prepositions

Field names: Prepositions

This rule enforces that field names do not include most prepositions, as mandated in AEP-140.

Details

This rule looks at each field and complains if it sees any of the following words in the method’s name:

{% include prepositions.md %}

Note: The standard fields order_by and group_by are permitted.

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  string name = 1;
  string written_by = 2;  // Should be `author`.
}

Correct code for this rule:

// Correct.
message Book {
  string name = 1;
  string author = 2;
}

Disabling

If you need to violate this rule, use a leading comment above the field. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0140::prepositions=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  string name = 1;
  string written_by = 2;
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

Field names- Reserved words

Field names: Reserved words

This rule enforces that field names are not reserved words, as mandated in AEP-140.

Details

This rule looks at each field and complains if it the name is a reserved word in a common programming lanaguge.

Currently, the linter checks all the reserved words in Java, JavaScript, and Python 3. The exhaustive list of reserved words is found in the code.

Note: Reserved words in Golang are permitted because Golang’s variable casing rules avoids a conflict.

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  string name = 1;
  bool public = 2;  // Reserved word in Java, JavaScript
}

Correct code for this rule:

// Correct.
message Book {
  string name = 1;
  bool is_public = 2;
}

Disabling

If you need to violate this rule, use a leading comment above the field. Remember to also include an aep.dev/not-precedent comment explaining why.

message Book {
  string name = 1;
  // (-- api-linter: core::0140::reserved-words=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  bool public = 2;  // Reserved word in Java, JavaScript
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

Field names- Underscores

Field names: Underscores

This rule enforces that field names do not use leading, trailing, or adjacent underscores, as mandated in AEP-140.

Details

This rule checks every field in the proto and complains if it sees leading or trailing underscores, or two or more underscores with nothing in between them.

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  string name = 1;
  string _title = 2;  // Should be `title`.
}

Correct code for this rule:

// Correct.
message Book {
  string name = 1;
  string title = 2;
}

Disabling

If you need to violate this rule, use a leading comment above the method. Remember to also include an aep.dev/not-precedent comment explaining why.

Warning: Violating this rule is likely to run into tooling failures.

// (-- api-linter: core::0140::underscores=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  string name = 1;
  string _title = 2;
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

Field names- URIs

Field names: URIs

This rule enforces that field names use uri rather than url, as mandated in AEP-140.

Details

This rule checks every field in the proto and complains if the field name includes url. (It splits on _ to avoid false positives.)

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  string url = 1;  // Should be `uri`.
}

Correct code for this rule:

// Correct.
message Book {
  string uri = 1;
}

Disabling

If you need to violate this rule, use a leading comment above the method. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0140::uri=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
message Book {
  string url = 1;
}

If you need to violate this rule for an entire file, place the comment at the top of the file.