Skip to content

Should we rename "identity" as "reference" in javadoc? #735

Closed
Closed
Should we rename "identity" as "reference" in javadoc?#735
Assignees
ajkannan
Labels
type: questionRequest for information or clarification. Not an issue.

Description

@ajkannan
ajkannan
opened on Mar 10, 2016

In services that have model objects with "id" as a field, we try to differentiate between that "id" field and the "identity" of that object (the information necessary to reconstruct/access that object via the service). For example, blobs have "id" fields, but gcloud-java-storage also has a BlobId class that contains the bucket name, blob name, and generation.

In the javadoc, we use "identity" to describe classes like BlobId. I feel that "reference" is a slightly better word than "identity" because "reference" is a more commonly used word and thus would make the javadoc read more nicely. Also, "id" is a shorthand for "identity" (and a user could potentially assume they're related), whereas "reference" might differentiate the two items more clearly.

Activity

  1. ajkannan
    added
    type: questionRequest for information or clarification. Not an issue.
    docs
    on Mar 10, 2016

  2. mziccard commented on Mar 10, 2016

    @mziccard
    mziccard
    on Mar 10, 2016
    Contributor

    I agree that reference is more commonly used but also has a different meaning in the context of programming.

  3. mderka commented on Mar 11, 2016

    @mderka
    mderka
    on Mar 11, 2016

    -1 for this rename. I have seen "identity" referring to a rather complex compounded object descriptor which is exactly what we are doing in this case. Thus, it seems natural. I would be struggling with understanding the meaning of a "reference".

  4. ajkannan commented on Mar 12, 2016

    @ajkannan
    ajkannan
    on Mar 12, 2016
    Author

    Alright, closing this as it seems like identity is more popular.

  5. ajkannan
    closed this as completedon Mar 12, 2016
  6. JustinBeckwith
    assigned
    ajkannan
    on Feb 1, 2021
  7. github-actions
    added 2 commits that reference this issue on Jun 23, 2022

    chore(main): release 2.2.1 (#735)

    af4296d

    chore: update java template (googleapis#1367) (googleapis#735)

    f4c4dbc
  8. github-actions
    added a commit that references this issue on Aug 9, 2022

    chore(deps): update dependency com.google.cloud:google-cloud-tasks to…

    b5f168d
  9. github-actions
    added 2 commits that reference this issue on Aug 16, 2022

    chore(main): release 2.2.3 (#735)

    597202e

    build(deps): update dependency org.apache.maven.plugins:maven-javadoc…

    b8cc460
  10. github-actions
    added a commit that references this issue on Sep 15, 2022

    chore(bazel): Update WORKSPACE files for rules_gapic, gax_java, gener…

    62eb6ab
  11. github-actions
    added 2 commits that reference this issue on Oct 4, 2022

    chore(main): release 2.4.5 (#734)

    7cd7f8c

    chore(main): release 2.4.4 (#740)

    2460ef2

  12. 5 remaining items

  13. suztomo
    added a commit that references this issue on Feb 1, 2023

    chore(main): release 3.0.0 (#740)

    f0625b0
  14. meltsufin
    added a commit that references this issue on Dec 22, 2025

    chore(deps): update dependency com.google.cloud:google-cloud-logging …

    aad3d80
  15. chingor13
    added a commit that references this issue on Jan 6, 2026

    chore(deps): update dependency com.google.cloud:google-cloud-logging-…

    4a996f7
  16. chingor13
    added a commit that references this issue on Jan 22, 2026

    chore(deps): update dependency com.google.cloud:libraries-bom to v25.…

    a057ecb
  17. chingor13
    added a commit that references this issue on Feb 24, 2026

    chore: update java docfx doclet (#735)

    2093aad
  18. suztomo
    added a commit that references this issue on Mar 11, 2026

    chore(deps): update dependency com.google.cloud:google-cloud-logging …

    4de162a
  19. chingor13
    added a commit that references this issue on Mar 12, 2026

    chore: update java docfx doclet (#735)

    52295e7
  20. suztomo
    added a commit that references this issue on Mar 23, 2026

    build(deps): update dependency org.apache.maven.plugins:maven-project…

    da92c7a
  21. suztomo
    added 2 commits that reference this issue on Mar 30, 2026

    deps: update dependency com.google.cloud:google-cloud-storage to v2.1…

    8469d3b

    chore: release 0.123.15 (#736)

    2f2555e
  22. lqiu96
    added 2 commits that reference this issue on Apr 1, 2026

    deps: update dependency com.google.cloud:google-cloud-storage to v2.1…

    e2f2c95

    chore: release 0.123.15 (#736)

    6af79eb
  23. meltsufin
    added 2 commits that reference this issue on Apr 29, 2026

    chore: remove distributionManagement section (#735)

    84040e1

    chore: remove distributionManagement section (#735)

    7ec67c4
  24. benjaminp
    added a commit that references this issue on Jul 13, 2026

    chore: regenerate README (googleapis#735)

    a764d25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

type: questionRequest for information or clarification. Not an issue.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions
    Sponsor
    SponsoredKunjungi sekarang
    Promo