Document voting method implementations - #59
Merged
Conversation
Co-authored-by: Cursor <cursoragent@cursor.com>
Reviewer's GuideThis PR adds detailed, consistent docstrings for all major voting method implementations and their factories, clarifying ballot formats, scoring scales, tabulation rules, and simulator result semantics, without changing functional behavior. File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- For the factory functions (Score, Srv, BulletyApprovalWith), consider being explicit in the docstrings about the exact return type (instance vs. subclass) and any expectations about subclassing, so users understand how to compose these with other method factories.
- Where you mention that "larger values indicate stronger preference" or encode candidate ordering, it may help to explicitly state whether results are normalized scores, raw tallies, or ordinal ranks to avoid ambiguity when interpreting simulator outputs across different methods.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- For the factory functions (Score, Srv, BulletyApprovalWith), consider being explicit in the docstrings about the exact return type (instance vs. subclass) and any expectations about subclassing, so users understand how to compose these with other method factories.
- Where you mention that "larger values indicate stronger preference" or encode candidate ordering, it may help to explicitly state whether results are normalized scores, raw tallies, or ordinal ranks to avoid ambiguity when interpreting simulator outputs across different methods.
## Individual Comments
### Comment 1
<location path="src/vse_sim/methods/borda.py" line_range="8-10" />
<code_context>
class Borda(Method):
+ """Implement Borda count with larger rank values representing preference.
+
+ Honest ballots assign consecutive scores from least to most preferred.
+ Ranked methods also inherit this class's ballot construction and strategy
+ helpers.
</code_context>
<issue_to_address>
**suggestion:** Clarify how ranks map to preferences and scores to avoid confusion with conventional Borda.
The phrases "larger rank values representing preference" and "consecutive scores from least to most preferred" are unclear, especially since classical Borda typically treats smaller ranks as more preferred. If this implementation reverses that convention (e.g., 0 = least preferred and higher values = more preferred), please state that explicitly and add a brief example ballot to illustrate the ranking and scoring direction for readers familiar with standard Borda.
</issue_to_address>
### Comment 2
<location path="src/vse_sim/methods/bullety_approval.py" line_range="8-12" />
<code_context>
def BulletyApprovalWith(bullets=0.5, asClass=False):
+ """Create approval voting with a configurable share of bullet voters.
-
+ Each honest ballot is either ordinary normalized approval or a bullet vote
+ for all utility-maximizing candidates. ``bullets`` is the probability of
+ bullet voting.
+ """
</code_context>
<issue_to_address>
**suggestion:** Tighten the description of how `bullets` is interpreted and any expected range.
The current docstring doesn’t specify the expected range for `bullets` or how the probability is applied. Please clarify that `bullets` is a float in [0, 1] and that it’s applied independently per honest ballot (e.g., “`bullets` is the independent probability that an honest voter casts a bullet ballot rather than a normalized approval ballot”). This will help avoid misconfiguration.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
+8
to
+10
| """Implement Borda count with larger rank values representing preference. | ||
|
|
||
| Honest ballots assign consecutive scores from least to most preferred. |
There was a problem hiding this comment.
suggestion: Clarify how ranks map to preferences and scores to avoid confusion with conventional Borda.
The phrases "larger rank values representing preference" and "consecutive scores from least to most preferred" are unclear, especially since classical Borda typically treats smaller ranks as more preferred. If this implementation reverses that convention (e.g., 0 = least preferred and higher values = more preferred), please state that explicitly and add a brief example ballot to illustrate the ranking and scoring direction for readers familiar with standard Borda.
Comment on lines
8
to
+12
| def BulletyApprovalWith(bullets=0.5, asClass=False): | ||
| """Create approval voting with a configurable share of bullet voters. | ||
|
|
||
|
|
||
| Each honest ballot is either ordinary normalized approval or a bullet vote | ||
| for all utility-maximizing candidates. ``bullets`` is the probability of |
There was a problem hiding this comment.
suggestion: Tighten the description of how bullets is interpreted and any expected range.
The current docstring doesn’t specify the expected range for bullets or how the probability is applied. Please clarify that bullets is a float in [0, 1] and that it’s applied independently per honest ballot (e.g., “bullets is the independent probability that an honest voter casts a bullet ballot rather than a normalized approval ballot”). This will help avoid misconfiguration.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Stack
Depends on #58. Retarget this PR to
mainafter #58 merges.Validation
uv run python -m pytest(44 passed)trunk checkSummary by Sourcery
Documentation: