Taylor Blau <me@xxxxxxxxxxxx> writes: > On Tue, Oct 22, 2024 at 03:45:38AM -0500, karthik nayak wrote: >> >> So, that being said, I agree that we shouldn't use arbitrary suffixes, >> >> as these are quite hard to understand indeed and typically don't really >> >> provide any context. So as long as we interpret this rule leniently I'm >> >> happy with it. >> > >> > I am not sure here... I think that using a "_1()" suffix means that the >> > function is processing one of a number of elements that all need to be >> > handled similarly, but where both the processing of an individual >> > element, and the handling of a group of elements are both complicated >> > enough to be placed in their own function. >> >> The crux here is that this meaning is internalized by people who know >> the code through in and out. But for anyone new to the project, this is >> not evident from the naming. > > Right. I think that with that in mind, a good goal might be to document > that convention to make sure that newcomers to the project can easily > interpret what foo() and foo_1() mean. Another approach is the one you > pursue here, which is to change the existing convention in the name of > making the code more approachable for newcomers. > > Both approaches meet the same end, but the former does not involve > changing existing conventions, but instead documenting them. That seems > like a more reasonable path to me. > I would disagree though. I think some conventions even though we've been using them for a while, should be changed. I guess a good middle ground is to document current behavior while also discouraging future use. I'll add that in and push a new version. >> > It's also a helpful convention when you have a recursive function that >> > does some setup during its initial call, but subsequent layers of >> > recursion don't need or want to repeat that setup. >> > >> >> I get the usecase of having such functions. I totally see the need, it's >> mostly the naming that I'm trying to change. >> >> Let's consider two of such functions: >> >> 1. mark_remote_island_1: This function is called to do _some_ work on a >> single remote island when iterating over a list. >> 2. find_longest_prefixes_1: This is a recursive function which is used >> to find the longest prefix. >> >> If you notice, both use the "_1" suffix and do different things (operate >> on a single instance from a list vs provide recursive behavior). So the >> user has to read the code to understand, which makes the "_1" a bit >> confusing. >> >> Second, this could have instead been named: >> 1. mark_single_remote_island: Which reads better, giving the idea that >> we are really working on a single remote island. Whereas having a "_1" >> doesn't easily imply the same. >> 2. find_longest_prefixes_recursively: Which also reads better, and gives >> a hint on how the function operates and why it is split out from the >> base function. > > I don't disagree that writing "single" or "recursively" can be > considered clearer. I think that the convention to suffix such functions > with "_1()" is more terse, but saves characters and can avoid awkward > line wrapping. > But are those pros worth the ambiguity it brings? > Thanks, > Taylor - Karthik
Attachment:
signature.asc
Description: PGP signature
