docs: add guidance on initialism capitalisation in PascalCase identifiers. #32720

pull Muniru0 wants to merge 1 commits into bitcoin:master from Muniru0:dev-notes-style-camelcase changing 1 files +6 −0
  1. Muniru0 commented at 6:35 pm on June 10, 2025: none

    Fixes #32698

    Problem Inconsistent initialization of class,function, method identifiers and structs. Spread throughout the codebase is screaming / acronym caps.

    Solution

    • Add a rule in the developer notes to use consistent camelcase naming convention.
    • A class names like JSONRPCRequest should be JsonRpcRequest.
  2. DrahtBot commented at 6:35 pm on June 10, 2025: contributor

    The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

    Code Coverage & Benchmarks

    For details see: https://corecheck.dev/bitcoin/bitcoin/pulls/32720.

    Reviews

    See the guideline for information on the review process.

    Type Reviewers
    ACK janb84, maflcko

    If your review is incorrectly listed, please react with 👎 to this comment and the bot will ignore it on the next update.

  3. DrahtBot added the label Docs on Jun 10, 2025
  4. Muniru0 force-pushed on Jun 10, 2025
  5. DrahtBot added the label CI failed on Jun 10, 2025
  6. DrahtBot commented at 6:51 pm on June 10, 2025: contributor

    🚧 At least one of the CI tasks failed. Task lint: https://github.com/bitcoin/bitcoin/runs/43835056566 LLM reason (✨ experimental): The CI failure is caused by a lint check error related to trailing whitespace in a documentation file.

    Try to run the tests locally, according to the documentation. However, a CI failure may still happen due to a number of reasons, for example:

    • Possibly due to a silent merge conflict (the changes in this pull request being incompatible with the current code in the target branch). If so, make sure to rebase on the latest commit of the target branch.

    • A sanitizer issue, which can only be found by compiling with the sanitizer and running the affected test.

    • An intermittent issue.

    Leave a comment here, if you need help tracking down a confusing failure.

  7. DrahtBot removed the label CI failed on Jun 10, 2025
  8. in doc/developer-notes.md:103 in 3f9e82c4cb outdated
     99@@ -100,6 +100,11 @@ code.
    100     naming style](#internal-interface-naming-style) for an exception to this
    101     convention.
    102 
    103+  - With `PascalCase`, do not to use [screaming/acronym caps](https://gist.github.com/adashrod/66564c690906c9b774e77ddacbd06e1b). Legacy identifiers that violate this rule remain for compatibility and will be renamed gradually. Hence:
    


    maflcko commented at 7:28 am on June 11, 2025:
    “do not to use” -> “do not use” [remove redundant “to”]
    

    Also, not sure about linking to a private third-party rant as a rationale


    Muniru0 commented at 7:40 am on June 11, 2025:
    Well, I will correct both. But I don’t see that as a rant if the person is making legitimate points.

    maflcko commented at 7:43 am on June 11, 2025:
    the filename is ...rant.md, also external private third-party content is likely to change or disappear

    Muniru0 commented at 7:48 am on June 11, 2025:
    okay, now I get you. Thanks.

    JeremyRand commented at 9:23 am on June 12, 2025:

    I think it’s useful to document the reason for the policy (so that any future proposed revisions to the policy understand what the goal was), although I concur with @maflcko that unstable external links are problematic for long-term preservation. I think this could be handled by including a brief summary of the reasoning inline (sufficient to grok what the point of the policy is), perhaps including an external link for attribution purposes.

    The actual content of the “rant” doesn’t appear unprofessional to me; it’s pretty much exclusively composed of technically coherent points. I suspect that the word “rant” in the description is intended either in self-deprecating jest, or as a reference to the motivation of writing the document (I assume the author intended to cite this document when criticizing various specific FLOSS projects’ practices on the subject). The document does seem a lot more thorough of a rationale for the policy than I had seen elsewhere (it raised some minor points that I wasn’t aware of when I filed the issue).

    I would have no issue with linking to that external document, as long as sufficient summary is included inline that a potential loss of the external link doesn’t cause undue confusion. At the very least, including a link for context is better than providing no context at all: if the link dies, the dead link is unlikely to provide negative value. I think it’s also good-neighbor behavior to attribute documents that influenced the policy; I certainly wouldn’t want people to omit attribution to my work just because they’re worried that the link might become inaccessible in the future.

  9. Muniru0 force-pushed on Jun 11, 2025
  10. in doc/developer-notes.md:103 in 8a93203797 outdated
     99@@ -100,6 +100,11 @@ code.
    100     naming style](#internal-interface-naming-style) for an exception to this
    101     convention.
    102 
    103+  - With `PascalCase`, do not use screaming/acronym caps. Legacy identifiers that violate this rule remain for compatibility and will be renamed gradually. Hence:
    


    janb84 commented at 11:21 am on June 12, 2025:
    0  - With `PascalCase`,  Acronyms must be treated as words. To minimize code churn, legacy identifiers that do not comply with this rule will remain unchanged and will only be renamed when the surrounding code is modified. Hence:
    

    NIT: Do not tell what NOT to do but explain what to do. This suggestion explains (imho) what the intention is, treating acronyms as words, and therefor the PascalCase can easily be applied.

  11. sipa commented at 11:24 am on June 12, 2025: member
    -0, I don’t see why this can’t be left to the author, given how rare it is.
  12. Muniru0 commented at 1:54 pm on June 12, 2025: none

    To balance attribution with long-term stability, I recommend that we:

    • Embed a succinct, self-contained summary of the policy’s reasoning directly in the developer notes, so that the purpose and benefits of the convention remain immediately accessible even if the external link breaks.

    Also take into consideration the nit of @janb84.

    With these clarifications or adjustments in place, I trust we can all concur on the final structure.

  13. Muniru0 force-pushed on Jun 15, 2025
  14. maflcko commented at 8:39 am on June 25, 2025: member
    Seems fine. No strong opinion, but at least the two lines of docs shouldn’t add several typos, see #32720 (comment)
  15. maflcko commented at 6:27 am on June 30, 2025: member
  16. Muniru0 commented at 8:15 am on June 30, 2025: none

    Please squash your commits according to https://github.com/bitcoin/bitcoin/blob/master/CONTRIBUTING.md#squashing-commits

    aaah, forgot. thanks

  17. docs: add guidance on initialism capitalisation in PascalCase identifiers b6f3b33500
  18. Muniru0 force-pushed on Jul 1, 2025
  19. janb84 commented at 12:44 pm on July 1, 2025: contributor

    reACK b6f3b335002a6fa5095bedb8ad22a71fce5d35fb

    Changes sinds last ACK:

    • Author fixed some typo’s
  20. maflcko commented at 12:52 pm on July 1, 2025: member
    lgtm ACK b6f3b335002a6fa5095bedb8ad22a71fce5d35fb

github-metadata-mirror

This is a metadata mirror of the GitHub repository bitcoin/bitcoin. This site is not affiliated with GitHub. Content is generated from a GitHub metadata backup.
generated: 2025-07-08 12:13 UTC

This site is hosted by @0xB10C
More mirrored repositories can be found on mirror.b10c.me